# Portfolio Kit

> 133 composable React components and 15 full-page templates for building portfolio websites, plus a theme builder. Built on shadcn/ui + Tailwind CSS v4 and installed with the shadcn CLI (`npx shadcn@latest add @portfolio-kit/<name>`). Individual guides, components and templates have Markdown counterparts linked below.

Components are installed as source into `components/portfolio/`, compose as compound parts (`ProjectCard` + `ProjectCardTitle`…), accept `className` on every part and follow the theme tokens. Pick a template for a whole page, or compose sections from components.

## Docs

- [Agent integration instructions](https://www.parthjadhav.com/products/portfolio-kit/AGENTS.md): inspect the consumer, install components, preserve accessibility and verify the result.
- [Product brief](https://www.parthjadhav.com/products/portfolio-kit/agent.md): scope, installation model and development-only availability.
- [Introduction](https://www.parthjadhav.com/products/portfolio-kit/docs/introduction.md): What Portfolio Kit is, how it's organized, and how to use it.
- [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md): Connect the registry once, then add components and templates with the shadcn CLI.
- [Build your portfolio](https://www.parthjadhav.com/products/portfolio-kit/docs/build-your-portfolio.md): A ten-minute walkthrough: install a template, theme it, swap in your content, add a project gallery and deploy.
- [Theming](https://www.parthjadhav.com/products/portfolio-kit/docs/theming.md): Make your own theme in the builder, the tokens behind it, dark mode, and several themes on one site.
- [Customization](https://www.parthjadhav.com/products/portfolio-kit/docs/customization.md): Compose parts, restyle anything with className, pick variants, and edit the source.
- [AI & agents](https://www.parthjadhav.com/products/portfolio-kit/docs/agents.md): Markdown versions of every page, llms.txt, the shadcn MCP server and rules to paste into your AGENTS.md.
- [Theme builder](https://www.parthjadhav.com/products/portfolio-kit/themes.md): make a theme (accent, neutrals, fonts, radius, shadows); options, share-URL format and the default CSS.

## Templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md): A single long-form post: a magazine title block, a reading column with margin sidenotes, link previews, a wide figure and a pull quote, then the author, a newsletter sign-up and related posts. Prints cleanly.
- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md): A long-form case study page for a single project, with a facts header, chapter navigation, mockups, a before/after slider and results.
- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md): An award-site portfolio for a creative developer, with a short intro, smooth scrolling, a custom cursor, sideways work and a curtain footer.
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md): An image-led studio site for a designer or art director, with a big typographic intro, large project images and a short studio page.
- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md): A software engineer's site with a pinned intro and ⌘K menu on the left, and experience, projects, open source and writing on the right.
- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md): A one-person studio site that sells: a clear offer, case studies with results, services with prices, an FAQ and a contact form next to a call booker.
- [Links](https://www.parthjadhav.com/products/portfolio-kit/templates/links.md): A link-in-bio page for your social profiles: portrait, name and one line, availability, a stack of link buttons with one featured, your latest post, what you're listening to and a newsletter sign-up.
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md): A text-first, single-column personal site: a short intro, then quiet labelled lists of work, writing and talks.
- [Not Found](https://www.parthjadhav.com/products/portfolio-kit/templates/not-found.md): A 404 page with some personality: a huge scrambling “404”, one honest sentence, the pages people usually want instead, and a ⌘K search to find the rest.
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md): A quiet, image-first portfolio for a photographer or filmmaker, with a featured series, a filterable index with a lightbox and a short bio.
- [Résumé](https://www.parthjadhav.com/products/portfolio-kit/templates/resume.md): A one-page, Swiss-style CV that reads well on screen and prints cleanly to A4 or Letter: positioning, contact row, experience, selected projects, skills, education, recognition and languages.
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md): A site for people who mainly talk and teach: the next talk up front, every talk by year, podcast clips you can play, and a way for organisers to book you.
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md): A small studio or agency site: a statement, a reel, stacked featured work, clients, services, awards and the team, behind a full-screen menu.
- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md): A quiet side page for a developer's site: what I'm doing now, the hardware, software and desk I use, what I'm reading and listening to, the sites I follow and a short page history.
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md): A warm, editorial home for an essayist or newsletter author: a masthead with sign-up, the latest letter and recent essays, a book spread, a reading shelf, talks and a closing subscribe band.

## Layout

- [Announcement Bar](https://www.parthjadhav.com/products/portfolio-kit/components/announcement-bar.md): Slim banner above the header for launches and availability. Static, accent-filled or scrolling, with an optional close button that can be remembered.
- [Bento Grid](https://www.parthjadhav.com/products/portfolio-kit/components/bento-grid.md): Six-column grid of spanning cards with labels, titles and full-bleed visuals, for about sections, stats and tool stacks.
- [Footer Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/footer-reveal.md): The curtain footer: the page lifts away at the end to reveal the footer waiting underneath. Pure CSS sticky, with an optional lift-in effect.
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md): Page section with container widths, vertical spacing and a composable header: eyebrow, title, description and actions.
- [Site Footer](https://www.parthjadhav.com/products/portfolio-kit/components/site-footer.md): Site footer with link columns, a small-print row and an optional giant wordmark that fills the full width.
- [Sticky Layout](https://www.parthjadhav.com/products/portfolio-kit/components/sticky-layout.md): Two-column page layout: a pinned intro with scrollspy navigation on the left and scrolling sections on the right.

## Navigation

- [Back To Top](https://www.parthjadhav.com/products/portfolio-kit/components/back-to-top.md): Floating button that appears after scrolling, shows page progress around its edge and scrolls back to the top.
- [Command Menu](https://www.parthjadhav.com/products/portfolio-kit/components/command-menu.md): A ⌘K palette for jumping to pages, projects and actions, with fuzzy search, grouped results and keyboard hints. Pass data or compose the parts yourself.
- [Floating Dock](https://www.parthjadhav.com/products/portfolio-kit/components/floating-dock.md): A macOS-style navigation dock. Icons grow toward the pointer, labels appear above them and the current page gets a dot.
- [Language Switch](https://www.parthjadhav.com/products/portfolio-kit/components/language-switch.md): Links to the translated versions of a page, as “EN / DE / FR” text, a segmented pill or a globe menu. Sets `hrefLang`, `lang` and `aria-current` for you.
- [Overlay Menu](https://www.parthjadhav.com/products/portfolio-kit/components/overlay-menu.md): Full-screen menu with a Menu ↔ Close morphing trigger, big numbered links, hover previews and a footer slot.
- [Pill Nav](https://www.parthjadhav.com/products/portfolio-kit/components/pill-nav.md): Segmented navigation with a sliding pill that follows the pointer and rests on the current page.
- [Scroll Progress](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-progress.md): Reading-progress indicator for the page or a single article, as a thin bar across the top or a small ring with a percentage.
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md): Sticky header with brand, nav, actions and a full-screen mobile menu. Bar or floating-pill style, optional hide-on-scroll.
- [Table Of Contents](https://www.parthjadhav.com/products/portfolio-kit/components/table-of-contents.md): Scrollspy navigation for case studies and articles, as a rail with a moving marker or a plain list. Clicking scrolls to the heading and updates the URL hash.
- [Theme Picker](https://www.parthjadhav.com/products/portfolio-kit/components/theme-picker.md): Switch between `data-theme` presets with round color swatches or a labelled list, on <html> or any element, and optionally remember the choice.
- [Theme Toggle](https://www.parthjadhav.com/products/portfolio-kit/components/theme-toggle.md): Light, dark and system switch, as a sun/moon icon button or a three-way segmented control, that remembers the choice and follows the OS.

## Hero

- [Availability Badge](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge.md): Status pill with a pulsing dot that says whether you're taking work, e.g. “Available for work” or “Booked until March”.
- [Hero Intro](https://www.parthjadhav.com/products/portfolio-kit/components/hero-intro.md): The main portfolio hero: eyebrow, display title, lead, actions, optional media and a bottom meta row, with a staggered CSS entrance. Stacked, split or centered.
- [Hero Statement](https://www.parthjadhav.com/products/portfolio-kit/components/hero-statement.md): Oversized typographic hero. Lines slide up from a mask, inline media pills widen on hover, and a labeled meta grid sits underneath.
- [Hero Video](https://www.parthjadhav.com/products/portfolio-kit/components/hero-video.md): A full-bleed hero over a muted, looping background video, with a legible scrim and a visible pause button; it shows the poster under reduced motion or Save-Data and rests while off screen.
- [Local Time](https://www.parthjadhav.com/products/portfolio-kit/components/local-time.md): Live clock for your city (“Lisbon 14:32 GMT+1”) with a day/night icon and an optional blinking colon.
- [Location Tag](https://www.parthjadhav.com/products/portfolio-kit/components/location-tag.md): “Based in Lisbon, Portugal” with a map pin, optional coordinates in mono and an optional link to a map.
- [Profile Card](https://www.parthjadhav.com/products/portfolio-kit/components/profile-card.md): Link-in-bio style card with avatar, name, role, location, status, bio, socials and a primary action. Vertical card or compact row.
- [Scroll Cue](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-cue.md): “Scroll” indicator for full-height heroes: a moving line, a mouse with a rolling wheel or a bobbing arrow. Can link to the next section.
- [Showreel](https://www.parthjadhav.com/products/portfolio-kit/components/showreel.md): A large poster with a play button that follows the cursor; it opens your reel in a full-screen player (or plays it in place), with a duration label and a quiet coming-soon state.
- [Word Rotate](https://www.parthjadhav.com/products/portfolio-kit/components/word-rotate.md): Cycles words inside a headline with a slide-and-blur swap, in a slot as wide as the widest word so the line never reflows. Screen readers get one static sentence.

## About

- [Bio](https://www.parthjadhav.com/products/portfolio-kit/components/bio.md): About-me block with a captioned portrait, prose that opens with a lead paragraph, a facts list and an optional sign-off.
- [Credentials](https://www.parthjadhav.com/products/portfolio-kit/components/credentials.md): Education, certifications, courses and awards as rows with a kind icon, issuer, date and an optional verify link.
- [Credits List](https://www.parthjadhav.com/products/portfolio-kit/components/credits-list.md): Colophon-style credits: roles paired with the people behind them (optionally linked), as ruled columns, centered film credits or one compact inline line.
- [Dot Map](https://www.parthjadhav.com/products/portfolio-kit/components/dot-map.md): A dotted world map with pins for where you’re based, your clients or your travels, plus optional pulsing and connecting arcs. Pure SVG, no map library.
- [Experience](https://www.parthjadhav.com/products/portfolio-kit/components/experience.md): Work history as a hover-focus list, a vertical timeline that marks the current role, or compact résumé rows.
- [Now](https://www.parthjadhav.com/products/portfolio-kit/components/now.md): A /now page block listing what you're building, reading and learning, with an “updated” date. Card grid or divided list.
- [Photo Stack](https://www.parthjadhav.com/products/portfolio-kit/components/photo-stack.md): A pile of 3–5 photos that fans out on hover or keyboard focus. Click, tap or press Enter to send the top photo to the back.
- [Portrait](https://www.parthjadhav.com/products/portfolio-kit/components/portrait.md): A personal photo as a matted frame, tilted polaroid, arch or circle, with a subtle hover effect.
- [Principles](https://www.parthjadhav.com/products/portfolio-kit/components/principles.md): Numbered values or process steps (01, 02, 03…) as a card grid or divided rows with large numbers.
- [Signature](https://www.parthjadhav.com/products/portfolio-kit/components/signature.md): A handwritten SVG signature that writes itself, stroke by stroke, when it scrolls into view — the sign-off at the end of a bio or letter.
- [Skill Groups](https://www.parthjadhav.com/products/portfolio-kit/components/skill-groups.md): Skills grouped by discipline, as chips or level bars. Each skill can show a 1–5 level, years of use and an icon.
- [Stats](https://www.parthjadhav.com/products/portfolio-kit/components/stats.md): Headline numbers (years, projects, stars, awards) that count up as they scroll into view. Plain, divided or card layouts.
- [Timeline](https://www.parthjadhav.com/products/portfolio-kit/components/timeline.md): Milestones on a vertical or alternating rail with dates, icons or media, a current step, and dots that can fill as they scroll into view.
- [Tool Grid](https://www.parthjadhav.com/products/portfolio-kit/components/tool-grid.md): A /uses page: tools grouped by category, with logos or monogram tiles, short notes, favorites and optional links.

## Work

- [Archive Table](https://www.parthjadhav.com/products/portfolio-kit/components/archive-table.md): Sortable table of every project (year, name, client, stack and link), grouped by year, with columns that collapse on small screens.
- [Before After](https://www.parthjadhav.com/products/portfolio-kit/components/before-after.md): Comparison slider for redesigns. Drag, click or use the keyboard to wipe between two layers, horizontally or vertically.
- [Case Study Header](https://www.parthjadhav.com/products/portfolio-kit/components/case-study-header.md): Opening of a case study: back link, display title, summary, a ruled facts grid (client, role, timeline, live site) and a cover image.
- [Case Study Section](https://www.parthjadhav.com/products/portfolio-kit/components/case-study-section.md): Case study chapter with a sticky numbered label, styled prose, pull quotes, outcome metrics and figures that can span the label column.
- [Color Swatches](https://www.parthjadhav.com/products/portfolio-kit/components/color-swatches.md): A project’s palette for case studies: named swatches with hex and OKLCH values you click to copy, WCAG contrast labels, and grid, strip or proportional (by usage) layouts.
- [Device Frame](https://www.parthjadhav.com/products/portfolio-kit/components/device-frame.md): Browser, phone, laptop and window frames for screenshots, videos or artwork, drawn with theme tokens.
- [Draggable Canvas](https://www.parthjadhav.com/products/portfolio-kit/components/draggable-canvas.md): An endless canvas of project tiles you drag, flick, scroll or arrow around, the award-site signature. Without JavaScript it’s a plain grid.
- [Expanding Panels](https://www.parthjadhav.com/products/portfolio-kit/components/expanding-panels.md): A row of tall project panels: hover or focus one and it widens to show its title and details while the others fold into vertical labels. Stacks into an accordion on phones.
- [Image Gallery](https://www.parthjadhav.com/products/portfolio-kit/components/image-gallery.md): Images in a grid, masonry columns or a scrolling strip, with a lightbox you can use by keyboard, swipe or buttons.
- [Lab Grid](https://www.parthjadhav.com/products/portfolio-kit/components/lab-grid.md): Dense grid of side projects, experiments and toys, each with a status (live, WIP, archived), a small preview and a one-line meta row. Also renders as compact text rows.
- [Lightbox](https://www.parthjadhav.com/products/portfolio-kit/components/lightbox.md): Click-to-expand viewer for images, artwork and video: the thumbnail zooms into a full-screen view you browse with arrows, keys or swipes.
- [Next Project](https://www.parthjadhav.com/products/portfolio-kit/components/next-project.md): End-of-case-study pager: a large “next project” link whose cover widens on hover, as a full-width hero or a previous/next split.
- [Photo Meta](https://www.parthjadhav.com/products/portfolio-kit/components/photo-meta.md): EXIF-style caption for photographs and film stills (camera, lens, focal length, aperture, shutter, ISO, place and date) as a mono line, a spec grid or an overlay on the image.
- [Project Card](https://www.parthjadhav.com/products/portfolio-kit/components/project-card.md): Composable work card with media, meta, title, summary and tags, in card, minimal or overlay style. The whole card is one link.
- [Project Carousel](https://www.parthjadhav.com/products/portfolio-kit/components/project-carousel.md): Scroll-snap carousel for projects with mouse drag, arrow keys, previous/next buttons, a slide counter and a progress bar. No dependencies.
- [Project Grid](https://www.parthjadhav.com/products/portfolio-kit/components/project-grid.md): Responsive grid for project cards: even rows, staggered columns, or a featured first project that spans two columns.
- [Project List](https://www.parthjadhav.com/products/portfolio-kit/components/project-list.md): Projects as large text rows, with a preview image that follows the cursor on desktop and thumbnails on mobile.
- [Scroll Steps](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-steps.md): Scrollytelling for case studies and process write-ups: steps of text scroll past a sticky media panel that cross-fades to the active step's image.
- [Stacked Cards](https://www.parthjadhav.com/products/portfolio-kit/components/stacked-cards.md): Featured projects as large sticky cards that stack while you scroll. Each card shrinks and dims as the next one covers it.
- [Type Specimen](https://www.parthjadhav.com/products/portfolio-kit/components/type-specimen.md): A typeface showcase for case studies: a big “Aa”, the font’s name and foundry, its weights, the character set and a size ladder, all set in the project’s font.
- [View Toggle](https://www.parthjadhav.com/products/portfolio-kit/components/view-toggle.md): Segmented grid / list / index switch with a sliding indicator, for choosing how a work section is laid out.

## Social Proof

- [Awards List](https://www.parthjadhav.com/products/portfolio-kit/components/awards-list.md): Awards table with award, organization, project and year per row, a “×3” count for repeat wins and an optional summary of totals.
- [Logo Cloud](https://www.parthjadhav.com/products/portfolio-kit/components/logo-cloud.md): Client logos or wordmarks as a bordered grid, a wrapping row or an endless marquee with a pause button. Muted by default, full color on hover.
- [Press List](https://www.parthjadhav.com/products/portfolio-kit/components/press-list.md): Press mentions with publication, headline, kind and date, as divided rows or a card grid. Each linked item is a single link.
- [Social Post](https://www.parthjadhav.com/products/portfolio-kit/components/social-post.md): A post from a social network as a card: author, handle, network icon, date, text with linked mentions, tags and URLs, optional media and reply/repost/like counts.
- [Testimonial Card](https://www.parthjadhav.com/products/portfolio-kit/components/testimonial-card.md): Client quote with author (avatar or initials), optional star rating and source link, shown as a card, a plain block or a large featured quote.
- [Testimonial Spotlight](https://www.parthjadhav.com/products/portfolio-kit/components/testimonial-spotlight.md): One large quote at a time with prev/next, dots or author tabs, and optional autoplay that pauses on hover, focus and reduced motion.

## Services

- [FAQ](https://www.parthjadhav.com/products/portfolio-kit/components/faq.md): Accordion of questions and answers, as ruled lines or cards, with optional FAQPage JSON-LD for search engines.
- [Pricing Table](https://www.parthjadhav.com/products/portfolio-kit/components/pricing-table.md): Two to four offers side by side (audit, sprint, retainer) with a featured tier, prices that switch with a billing toggle, aligned sections and a footnote.
- [Process Steps](https://www.parthjadhav.com/products/portfolio-kit/components/process-steps.md): How-I-work timeline of numbered steps with heading, description and duration, joined by a line. Stacks on mobile, runs in a row on large screens, and can mark a current step.
- [Service Card](https://www.parthjadhav.com/products/portfolio-kit/components/service-card.md): Offer or pricing card with name, description, price, a checklist of what's included and a call to action. A featured variant highlights the offer you recommend.
- [Service List](https://www.parthjadhav.com/products/portfolio-kit/components/service-list.md): Numbered list of services with big headings that expand to reveal details, deliverables, duration and price. Keyboard-accessible accordion.

## Content

- [Audio Player](https://www.parthjadhav.com/products/portfolio-kit/components/audio-player.md): An inline player for podcast clips, music, voice reels and sound design: a play button, a seek slider over an optional precomputed waveform and the time, on a native audio element, with one track playing at a time.
- [Blogroll](https://www.parthjadhav.com/products/portfolio-kit/components/blogroll.md): An indie-web “sites I read” list: a monogram tile, site name, author, one line on why, the domain and when it last posted, as a list or a compact grid, with an OPML/RSS row.
- [Bookshelf](https://www.parthjadhav.com/products/portfolio-kit/components/bookshelf.md): Reading list as a shelf of standing covers that tilt on hover, or as a detailed list with status, rating and notes. Books without artwork get a generated cover.
- [Changelog](https://www.parthjadhav.com/products/portfolio-kit/components/changelog.md): A dated "what changed" log for a portfolio or product page: releases with version, date and optional permalink, and changes labelled Added, Changed or Fixed in words.
- [Code Window](https://www.parthjadhav.com/products/portfolio-kit/components/code-window.md): Code for case studies and developer portfolios: file tabs, a language label, copy, line numbers, highlighted and diff lines, and soft wrap. Plain text by default; bring your own highlighter.
- [Contribution Graph](https://www.parthjadhav.com/products/portfolio-kit/components/contribution-graph.md): GitHub-style activity heatmap: weeks by weekdays in five levels of the theme's accent, with month and weekday labels, a legend and a total. Scrolls to the latest weeks on small screens.
- [Link Preview](https://www.parthjadhav.com/products/portfolio-kit/components/link-preview.md): An inline link that shows a small card (cover, title, description, site) on hover or keyboard focus; Escape closes it. On touch screens it's just a link.
- [Media Appearances](https://www.parthjadhav.com/products/portfolio-kit/components/media-appearances.md): Podcast episodes, video interviews and livestreams you appeared on, with show artwork, date, duration and listen/watch links per platform, as rows or cards.
- [Newsletter Form](https://www.parthjadhav.com/products/portfolio-kit/components/newsletter-form.md): Email sign-up form with inline validation and loading, success and error states. Pill-shaped inline field, stacked form or titled card.
- [Now Playing](https://www.parthjadhav.com/products/portfolio-kit/components/now-playing.md): Music widget: album art, track and artist with an animated equalizer while playing, or “Last played” with a date or relative time. Card or one-line inline style.
- [Post Card](https://www.parthjadhav.com/products/portfolio-kit/components/post-card.md): Article card with cover, category, title, excerpt, date, reading time and author, in vertical, horizontal or large overlay styles.
- [Post List](https://www.parthjadhav.com/products/portfolio-kit/components/post-list.md): Writing index for blogs and notes: compact dated rows, an archive grouped by year with a sticky year label, or detailed entries with excerpt and tags.
- [Product Card](https://www.parthjadhav.com/products/portfolio-kit/components/product-card.md): Shop card for courses, prints and templates: cover, badge, details, price with a compare-at discount and a call to action. The whole card is one link.
- [Prose](https://www.parthjadhav.com/products/portfolio-kit/components/prose.md): Article typography for blog posts and case studies: headings, lists, quotes, code, figures, tables and footnotes styled from your theme, with no typography plugin.
- [Repo Card](https://www.parthjadhav.com/products/portfolio-kit/components/repo-card.md): GitHub-style repository card with owner/name, description, language, stars, forks, last update and topics. The whole card is one link.
- [Sidenote](https://www.parthjadhav.com/products/portfolio-kit/components/sidenote.md): Tufte-style margin notes: numbered references in the text with the notes beside it on wide screens, and tap-to-expand inline notes on phones.
- [Talk List](https://www.parthjadhav.com/products/portfolio-kit/components/talk-list.md): Talks, workshops and podcast appearances with event, location, date and links to slides or recordings. Future dates get an “Upcoming” badge.

## Contact

- [Availability Calendar](https://www.parthjadhav.com/products/portfolio-kit/components/availability-calendar.md): The next months at a glance, each marked open, limited or booked in words and a fill pattern, so clients see when you can start.
- [Booking Card](https://www.parthjadhav.com/products/portfolio-kit/components/booking-card.md): An “intro call” card with the host, meeting details and the next open slots as selectable chips. The button links to your scheduler with the chosen time.
- [Contact Bar](https://www.parthjadhav.com/products/portfolio-kit/components/contact-bar.md): A slim bar pinned to the bottom of the screen on phones that keeps “Email me” and “Book a call” one tap away once the hero has scrolled past, without covering the end of the page.
- [Contact CTA](https://www.parthjadhav.com/products/portfolio-kit/components/contact-cta.md): Closing section of a portfolio with a large invitation, availability, a copy-email button and actions. Centered, split, or under a scrolling “Let's talk” line.
- [Contact Form](https://www.parthjadhav.com/products/portfolio-kit/components/contact-form.md): Project inquiry form with name, email, company, budget and project-type chips and a message with a character count. Includes inline validation and sending, success and error states.
- [Copy Email](https://www.parthjadhav.com/products/portfolio-kit/components/copy-email.md): Your email as a button that copies it on click and briefly shows “Copied!”. Pill, ghost or display-size styles, with an optional mailto link.
- [Resume Link](https://www.parthjadhav.com/products/portfolio-kit/components/resume-link.md): Download-your-CV link as a button with a bouncing download icon, or a file card with type, size and last-updated date.
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md): Profile links as icons, pills or text. Pass URLs and the brand icon and label are detected automatically.

## Effects

- [Aurora](https://www.parthjadhav.com/products/portfolio-kit/components/aurora.md): Slowly drifting gradient blobs in hues around your theme's highlight, used as a hero or card backdrop. Static under reduced motion.
- [Background Pattern](https://www.parthjadhav.com/products/portfolio-kit/components/background-pattern.md): Grid, dot, line, cross or diagonal background in pure CSS, colored from theme tokens, with edge fades and an optional highlight glow.
- [Circular Text](https://www.parthjadhav.com/products/portfolio-kit/components/circular-text.md): A rotating badge of text set around a circle (“Available for work · Available for work ·”) with a slot in the middle for an icon or link. Pauses on hover and keyboard focus; can speed up or reverse with scrolling.
- [Custom Cursor](https://www.parthjadhav.com/products/portfolio-kit/components/custom-cursor.md): A dot and trailing ring that follow the pointer, grow over links and buttons, and show a text label over elements with `data-cursor`. Page-wide or scoped to a container.
- [Grain](https://www.parthjadhav.com/products/portfolio-kit/components/grain.md): Film-grain noise overlay for the whole page or a single element, built from one cached SVG tile, with optional jitter and any blend mode.
- [Horizontal Scroll](https://www.parthjadhav.com/products/portfolio-kit/components/horizontal-scroll.md): A pinned section whose row of cards travels sideways as you scroll down, with a progress bar. On touch screens, small or short viewports, reduced motion and in print it's a native swipeable row with snap points.
- [Image Trail](https://www.parthjadhav.com/products/portfolio-kit/components/image-trail.md): Images that spawn along the cursor's path and fade out behind it, over a hero or section. Touch screens and reduced motion get a still collage instead.
- [Magnetic](https://www.parthjadhav.com/products/portfolio-kit/components/magnetic.md): Pulls a button or icon toward a nearby pointer and springs back when it leaves. An optional inner layer moves further for depth.
- [Marquee](https://www.parthjadhav.com/products/portfolio-kit/components/marquee.md): Endlessly scrolling row or column for client names, skills or testimonials, with edge fades, reverse direction, pause on hover or on demand and an optional scroll-velocity drive.
- [Page Transition](https://www.parthjadhav.com/products/portfolio-kit/components/page-transition.md): View Transitions helpers for any router: `startPageTransition()`, preset animations (fade, slide-up, curtain, zoom) and shared-element names. Instant with reduced motion or without browser support.
- [Parallax](https://www.parthjadhav.com/products/portfolio-kit/components/parallax.md): Scroll-linked depth: layers that drift slower or faster than the page, and media that glides inside its frame. One shared animation frame, paused offscreen, still with reduced motion and in print.
- [Preloader](https://www.parthjadhav.com/products/portfolio-kit/components/preloader.md): Intro screen with a 0–100 counter or cycling greetings, then a curtain lifts to reveal the page. Skippable with a click or any key, can show once per session, and skipped with reduced motion.
- [Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/reveal.md): Fades, lifts and un-blurs elements as they scroll into view, one by one or staggered across a group. Respects reduced motion.
- [Scramble Text](https://www.parthjadhav.com/products/portfolio-kit/components/scramble-text.md): Text that decodes from random glyphs, left to right, on mount, when it scrolls into view or on hover. The layout never shifts.
- [Scroll Text](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-text.md): A statement paragraph whose words light up one after another as the reader scrolls through it, tied to scroll position rather than played once.
- [Scroll Zoom](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-zoom.md): A cover image or video that starts as an inset card and grows to full-bleed while the reader scrolls past it, for case-study openers and showreels.
- [Smooth Scroll](https://www.parthjadhav.com/products/portfolio-kit/components/smooth-scroll.md): Lenis-powered inertial scrolling for the page or a container, with smooth anchor links and a useLenis() hook. Off under reduced motion; touch stays native.
- [Spotlight Card](https://www.parthjadhav.com/products/portfolio-kit/components/spotlight-card.md): Card with a soft glow that follows the pointer and a brighter rim on its border. Wrap cards in a group so one pointer lights the borders across a grid.
- [Sticker Board](https://www.parthjadhav.com/products/portfolio-kit/components/sticker-board.md): Playful stickers and polaroids scattered over a section that visitors can pick up, drag, drop and nudge with the arrow keys, with a spring settle and a reset.
- [Text Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/text-reveal.md): Splits a headline into words or characters that slide up from a mask, staggered, when it scrolls into view. The original text stays accessible.
- [Tilt Card](https://www.parthjadhav.com/products/portfolio-kit/components/tilt-card.md): 3D card that tilts toward the pointer with a moving glare and parallax layers (`data-depth`), easing back when the pointer leaves. Off on touch and reduced motion.

## Utilities

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md): Text link with an animated underline and a nudging arrow, for the end of a teaser or a section action. Detects external URLs and opens them safely.
- [Brand Icons](https://www.parthjadhav.com/products/portfolio-kit/components/brand-icons.md): Dependency-free social/brand glyphs (GitHub, X, LinkedIn, Dribbble…) plus URL → brand detection.
- [Filter Chips](https://www.parthjadhav.com/products/portfolio-kit/components/filter-chips.md): Single- or multi-select pill chips with optional counts — for filtering projects, posts or tags by category. Arrow-key navigable.
- [Fit Text](https://www.parthjadhav.com/products/portfolio-kit/components/fit-text.md): Text that scales to exactly fill its container's width, for giant footer wordmarks and hero names. Each line fits on its own, with any font.
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md): Deterministic SVG placeholder art from a seed string: product screenshots, landscapes and portraits, or abstract mesh, bauhaus, rings, waves and orb. Use it for covers, photos and avatars; it can take its colors from the theme.
- [Hover Video](https://www.parthjadhav.com/products/portfolio-kit/components/hover-video.md): A muted clip that plays while its card is hovered or focused with the keyboard, over a poster or artwork. Loads nothing until then, pauses off screen and in background tabs, and stays still on touch screens, with reduced motion or when saving data.
- [Kbd](https://www.parthjadhav.com/products/portfolio-kit/components/kbd.md): Keycaps and shortcut hints ("⌘K to search", "Press Esc") that show ⌘ or Ctrl for the visitor's platform and read as words to screen readers.
- [Marker](https://www.parthjadhav.com/products/portfolio-kit/components/marker.md): Hand-drawn highlights, underlines, circles, boxes and strikes for key words in a bio or headline, drawn on when they scroll into view.
- [Media](https://www.parthjadhav.com/products/portfolio-kit/components/media.md): Aspect-ratio frame for images, video or artwork, with blur-up loading, optional hover zoom and an optional caption.
- [Number Ticker](https://www.parthjadhav.com/products/portfolio-kit/components/number-ticker.md): Counts up to a number when it scrolls into view — locale-aware formatting, compact notation, prefix/suffix and zero layout shift.
- [Sound Toggle](https://www.parthjadhav.com/products/portfolio-kit/components/sound-toggle.md): A "Sound — On/Off" toggle button with equalizer bars for sites with ambient audio or UI sounds: off by default, remembered, and readable anywhere through `useSound()`.
- [Tag List](https://www.parthjadhav.com/products/portfolio-kit/components/tag-list.md): Pill tags for skills, stacks and topics — outline, soft or solid, with optional links, leading dots or icons and counts.
- [Terminal](https://www.parthjadhav.com/products/portfolio-kit/components/terminal.md): Terminal window for developer portfolios. When it scrolls into view, commands type themselves out (in at most 5 seconds), output lines follow and a block cursor blinks at the end.
- [Version Label](https://www.parthjadhav.com/products/portfolio-kit/components/version-label.md): Small-print footer line with version, last-updated date, copyright and edition number, plus a colophon that credits typefaces and tools.

## Optional

- [Full docs in one file](https://www.parthjadhav.com/products/portfolio-kit/llms-full.txt)
- [Registry index](https://www.parthjadhav.com/products/portfolio-kit/r/registry.json): shadcn registry with every item.


---

# Portfolio Kit agent instructions

> Add Portfolio Kit source components to an existing React application.

## Read before editing

- [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md): configure the registry, dependencies and framework boundaries.
- [Component and template catalog](https://www.parthjadhav.com/products/portfolio-kit/llms.txt): select an item and read its Markdown before installing.
- [Theming](https://www.parthjadhav.com/products/portfolio-kit/docs/theming.md): semantic tokens, fonts and dark mode.
- [Customization](https://www.parthjadhav.com/products/portfolio-kit/docs/customization.md): compound parts and consumer-owned source.

## Install and integrate

1. Inspect the consumer's package manager, React version, Tailwind setup, import aliases and existing components.json. Preserve its configuration.
2. Add the `@portfolio-kit` registry using `https://www.parthjadhav.com/products/portfolio-kit/r/{name}.json`, then install the chosen item with `npx shadcn@latest add @portfolio-kit/<name>`.
3. Installed components use @/components/portfolio, shared hooks use @/hooks, and helpers use @/lib. Adapt aliases to the consumer; @pk/ is private to this documentation website.
4. For the Next.js App Router, use a client boundary for components that need hooks or browser events. Keep static surrounding content in server components.
5. Compose the documented compound parts. Use className and semantic theme tokens; retain keyboard controls, focus rings, reduced motion and visible content without JavaScript.

## Verify the result

- Run the consumer's existing lint, type checks and production build.
- Review installed diffs, especially when reinstalling customized files. The CLI copies source; it does not keep installed files synchronized.
- Check desktop and mobile layouts, light and dark modes, keyboard interactions and reduced motion.

## Availability

Portfolio Kit is public. Its documentation, Markdown and registry are served at https://www.parthjadhav.com/products/portfolio-kit; the registry URL is `https://www.parthjadhav.com/products/portfolio-kit/r/{name}.json`. Source and releases: https://github.com/ParthJadhav/portfolio-kit.


---

# Portfolio Kit

> 133 React components, 15 portfolio templates and a shared theme builder.

Portfolio Kit is a shadcn registry, not an npm component package. Items are copied into the consumer application as editable source. The tested baseline is React 19 and Tailwind CSS v4.

- [Agent integration instructions](https://www.parthjadhav.com/products/portfolio-kit/AGENTS.md)
- [Catalog and Markdown index](https://www.parthjadhav.com/products/portfolio-kit/llms.txt)
- [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md)
- [Theme builder reference](https://www.parthjadhav.com/products/portfolio-kit/themes.md)

Published at https://www.parthjadhav.com/products/portfolio-kit. Source and releases: https://github.com/ParthJadhav/portfolio-kit.


---

# Introduction

> What Portfolio Kit is, how it's organized, and how to use it.

Portfolio Kit is a set of **133 components** and **15 full-page templates** for building portfolio websites with React, Tailwind CSS and [shadcn/ui](https://ui.shadcn.com).

It is not an npm package. Like shadcn/ui, the shadcn CLI copies each piece into your project as source, and from then on it's your code.

```bash
npx shadcn@latest add @portfolio-kit/hero-intro
```

## What's inside

The component list comes from a survey of 81 portfolio sites by developers, designers, photographers, studios and freelancers.

- **Layout**: sections, containers, bento grids, sticky two-column layouts, headers and footers.
- **Navigation**: site headers, pill navs, docks, overlay menus, a ⌘K command menu, scroll progress, table of contents, theme and language switches.
- **Hero**: intros, statements, showreels, availability badges, local time, location.
- **Work**: project cards, grids, lists, carousels, a draggable canvas, case-study headers and chapters, device frames, before/after sliders, galleries and a lightbox.
- **About**: bio, experience, timeline, skills, tools, stats, principles, credentials, credits, a dot map, "now" pages.
- **Social proof**: testimonials, logo clouds, press, awards.
- **Services**: service cards and lists, pricing tables, process steps, FAQ.
- **Content**: article typography, margin notes and link previews for writing; posts, talks, podcast appearances, repos, products, books, a blogroll, a contribution graph, now playing.
- **Contact**: calls to action, contact and booking forms, copy-to-clipboard email, social links.
- **Effects**: reveals, marquees, parallax, horizontal scroll, image trails, magnetic buttons, tilt and spotlight cards, text effects, grain, aurora, custom cursors, page transitions.
- **Utilities**: arrow links, media frames, brand icons, generative art, text that fits its width, tags and other small parts.

The [templates](https://www.parthjadhav.com/products/portfolio-kit/templates) are complete pages assembled from these components. To go from nothing to a deployed site, follow [Build your portfolio](https://www.parthjadhav.com/products/portfolio-kit/docs/build-your-portfolio).

## How the components are built

All components share the same typography recipes, spacing scale, radius, motion curve and color tokens. Colors, fonts, radius and heading style are CSS variables, so changing the theme changes every component at once.

Most components are compound: `ProjectCard` is used with `ProjectCardMedia`, `ProjectCardTitle` and so on, rather than a long list of props. Every part accepts `className` and passes other props through to its element. See [Customization](https://www.parthjadhav.com/products/portfolio-kit/docs/customization).

Shared conventions keep them consistent next to each other: the same small mono labels, pill heights, card padding, hover lift and arrow chips everywhere. Pieces from different categories sit together without adjustments.

They use semantic HTML, keyboard controls, visible focus rings and `prefers-reduced-motion`. Retain these behaviors when customizing installed source, and check your own page without JavaScript, with reduced motion and when printed. The native migration's checks are documented in [AI & agents](https://www.parthjadhav.com/products/portfolio-kit/docs/agents).

## How to use these docs

- Browse [Components](https://www.parthjadhav.com/products/portfolio-kit/components) and [Templates](https://www.parthjadhav.com/products/portfolio-kit/templates). Each example shows its live preview and the code to copy.
- Read [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation) to connect the registry. You only do this once.
- New here? [Build your portfolio](https://www.parthjadhav.com/products/portfolio-kit/docs/build-your-portfolio) walks through a whole site in about ten minutes.
- Make a theme in the [theme builder](https://www.parthjadhav.com/products/portfolio-kit/themes), or read [Theming](https://www.parthjadhav.com/products/portfolio-kit/docs/theming).
- If you work with a coding agent, read [AI & agents](https://www.parthjadhav.com/products/portfolio-kit/docs/agents). Individual guides, components and templates have Markdown counterparts; the introduction is at `/docs/introduction.md`.


---

# Installation

> Connect the registry once, then add components and templates with the shadcn CLI.

## 1. Start from a shadcn/ui project

Any React + Tailwind CSS v4 project set up with shadcn/ui works: Vite, Next.js, React Router, Astro and others. Both Radix and Base UI styles are supported. If you're starting fresh:

```bash
npx shadcn@latest init --template vite --name my-portfolio
```

The `--template` flag also takes `next`, `react-router` and `astro`. It creates the app with Tailwind CSS v4 and the `@/` alias ready.

Follow the [shadcn/ui installation guide](https://ui.shadcn.com/docs/installation) for your framework.

## 2. Add the registry

Add the `@portfolio-kit` namespace to `components.json`:

```json
{
  "registries": {
    "@portfolio-kit": "https://www.parthjadhav.com/products/portfolio-kit/r/{name}.json"
  }
}
```

Now anything in the kit installs by name.

## 3. Add components

```bash
npx shadcn@latest add @portfolio-kit/hero-intro @portfolio-kit/project-card
```

Components land in `components/portfolio/`. Shared hooks go in `hooks/` and helpers in `lib/`. Anything a component depends on (other kit components, shadcn/ui primitives, npm packages) is installed with it.

```tsx
import { ProjectCard, ProjectCardTitle } from "@/components/portfolio/project-card"
```

## 4. Make a theme (optional)

Components work with your existing shadcn/ui colors. The kit adds defaults for its few extra tokens. To change the accent, fonts, radius and shadows, make a theme in the [theme builder](https://www.parthjadhav.com/products/portfolio-kit/themes) and paste its CSS into your stylesheet. See [Theming](https://www.parthjadhav.com/products/portfolio-kit/docs/theming).

## Or start from a template

A template is a complete page built from the kit. Install one, edit the `content` object at the top of the file, and render it:

```bash
npx shadcn@latest add @portfolio-kit/template-developer
```

```tsx
import TemplateDeveloper from "@/components/template-developer"

export default function Page() {
  return <TemplateDeveloper />
}
```

[Build your portfolio](https://www.parthjadhav.com/products/portfolio-kit/docs/build-your-portfolio) walks through this end to end, from theming to deploying.

## Next.js and server components

Kit files don't include `"use client"`. Components that use hooks or event handlers (most interactive and animated ones, and every template) need it in the App Router: add `"use client"` as the first line of the installed file, or render it from a file that has it.

### `<img>` lint warnings

In a `create-next-app` project, `next lint` / `eslint` warns `@next/next/no-img-element` on the kit components that render images (profile-card, post-card, lightbox, media and a few others). The kit uses plain `<img>` on purpose: the same files install into Vite, React Router and Astro, where `next/image` doesn't exist. The warnings don't affect the build.

To use Next's image optimisation, swap the `<img>` in the installed file for `next/image`. Keep its `alt` and `className`, give it `width` and `height` (or `fill` with `sizes` inside a sized box), and allow remote hosts in `images.remotePatterns`. To keep `<img>` instead, turn the rule off for the kit's folder in `eslint.config.mjs`:

```js
const eslintConfig = defineConfig([
  ...nextVitals,
  ...nextTs,
  {
    files: ["components/portfolio/**"], // "src/components/portfolio/**" with a src/ directory
    rules: { "@next/next/no-img-element": "off" },
  },
])
```

## Without the namespace

You can also install any item straight from its URL, with no `components.json` changes:

```bash
npx shadcn@latest add https://www.parthjadhav.com/products/portfolio-kit/r/project-card.json
```

## Manual installation

Every component page has a **Manual** tab with its full source, the npm packages it needs and the kit files it imports. Copy the files to the paths shown and fix the import aliases if yours differ from `@/`.

Every component also needs the kit's base tokens (`highlight`, `success`, `border-hover`, the card shadow, the `font-heading` utility and motion keyframes). The CLI installs them automatically as `@portfolio-kit/base`. When copying by hand, copy them from [`base.json`](https://www.parthjadhav.com/products/portfolio-kit/r/base.json).

## Hosting the registry yourself

The registry files are static JSON in `website/private-products/portfolio-kit/assets/r/`. A separate host can serve that directory at `/r/`; point the consumer's `components.json` at the host's `/r/{name}.json`. Preserve every dependency item, including `base.json`.

The public registry is served by the website at `https://www.parthjadhav.com/products/portfolio-kit/r/{name}.json`, built from the same files. `bun run build` does not export Portfolio Kit to `dist/`.

## Updating installed components

The CLI copies source into your application. Registry changes do not update those files automatically.
Before reinstalling a component, commit or back up your customizations and review the incoming diff. The
project is currently at version 0.x; component APIs can change.

## Requirements

- React 19 (the tested baseline; React 18 compatibility is not guaranteed)
- Tailwind CSS v4
- `lucide-react` for icons (installed with components that use it)


---

# Build your portfolio

> A ten-minute walkthrough: install a template, theme it, swap in your content, add a project gallery and deploy.

This guide takes you from an empty folder to a deployed portfolio. It uses Vite; in Next.js or React Router the steps are the same apart from where you render the page (see the note in step 2).

## 1. Create the app

```bash
npx shadcn@latest init --template vite --name my-portfolio
cd my-portfolio
```

This creates a Vite + React + TypeScript app with Tailwind CSS v4, the `@/` import alias and `components.json` already set up. When it asks for a component library, any choice works: Base UI and Radix are both supported. Adding the kit to an existing app instead? Follow the [shadcn/ui installation guide](https://ui.shadcn.com/docs/installation) for your framework first (it needs Tailwind CSS v4 and the `@/` alias), then run `npx shadcn@latest init`.

Then add the kit's registry to `components.json`:

```json
{
  "registries": {
    "@portfolio-kit": "https://www.parthjadhav.com/products/portfolio-kit/r/{name}.json"
  }
}
```

## 2. Pick a template and install it

Browse the [templates](https://www.parthjadhav.com/products/portfolio-kit/templates) and pick the one closest to what you do. There are templates for developers, designers, writers, photographers and freelancers, plus a résumé, a link-in-bio page and a 404. This guide uses the Developer template:

```bash
npx shadcn@latest add @portfolio-kit/template-developer
```

The CLI adds the template as `src/components/template-developer.tsx` (Vite projects alias `@/` to `src/`), plus every kit component it uses (in `src/components/portfolio/`), the hooks and helpers they need, and the kit's base tokens. Render it as your page, in `src/App.tsx`:

```tsx
import TemplateDeveloper from "@/components/template-developer"

export default function App() {
  return <TemplateDeveloper />
}
```

Run `npm run dev`. You should see the full template with its sample content.

> In Next.js, render the template from `app/page.tsx`. Kit components use hooks, so add `"use client"` at the top of the template file (and of any kit component your bundler complains about).

## 3. Make it look like you

Open the [theme builder](https://www.parthjadhav.com/products/portfolio-kit/themes). Choose a **starting point** (Editorial for a serif look, Swiss for strict type, Terminal for mono everything…), then adjust the accent, neutrals, fonts, radius and shadows. The whole site, previews included, switches to your theme as you go. Use **Shuffle** to explore and **Undo** (⌘Z) to step back.

When you're happy, copy the **CSS** tab and replace the `:root` and `.dark` blocks in `src/index.css` with it. Install the font packages the builder lists and add its import lines. Or download `theme.json` and run `npx shadcn@latest add ./theme.json`. See [Theming](https://www.parthjadhav.com/products/portfolio-kit/docs/theming) for what each token does.

## 4. Swap in your content

Open `src/components/template-developer.tsx`. Everything the page says lives in one `content` object at the top of the file: your name, role, links, experience, projects and writing.

```tsx
const content: DeveloperContent = {
  name: "Your Name",
  role: "Senior engineer",
  tagline: "One sentence about the work you do and who it's for.",
  email: "you@example.com",
  // …experience, projects, open source, writing
}
```

The object is typed, so your editor tells you what each field expects. Delete entries you don't need; sections without content can be removed from the JSX below. Put your images in `public/` and reference them as `/lumen.jpg`.

## 5. Add a component

Say you want a card linking to one project, and a gallery for its page that you can click through. Install the two components:

```bash
npx shadcn@latest add @portfolio-kit/project-card @portfolio-kit/lightbox
```

```tsx
import { Lightbox, LightboxTrigger } from "@/components/portfolio/lightbox"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"

export function LumenCard() {
  return (
    <ProjectCard href="/work/lumen">
      <ProjectCardMedia>
        <img src="/lumen/cover.jpg" alt="" />
      </ProjectCardMedia>
      <ProjectCardContent>
        <ProjectCardTitle>Lumen</ProjectCardTitle>
        <ProjectCardDescription>
          A design system for eleven products.
        </ProjectCardDescription>
      </ProjectCardContent>
    </ProjectCard>
  )
}

export function LumenGallery() {
  return (
    <Lightbox label="Lumen" className="grid grid-cols-2 gap-4">
      <LightboxTrigger
        src="/lumen/dashboard.jpg"
        alt="The Lumen dashboard"
        className="col-span-2 aspect-video"
      />
      <LightboxTrigger src="/lumen/tokens.jpg" alt="Token pipeline" className="aspect-square" />
      <LightboxTrigger src="/lumen/mobile.jpg" alt="Lumen on a phone" className="aspect-square" />
    </Lightbox>
  )
}
```

Save this as `src/components/lumen.tsx`, then render `<LumenCard />` in your work section and `<LumenGallery />` on the project's page. Every component page shows more examples to copy, and its **API** section lists every prop. Components you install follow your theme automatically.

## 6. Check it

- Toggle dark mode and look at every section.
- Resize to phone width (390px): nothing should scroll sideways.
- Tab through the page: every link and button shows a focus ring.
- Turn on "reduce motion" in your OS settings: entrance effects are skipped and content shows at once.
- Print the page (or save as PDF): content hidden by scroll effects prints fully, and the résumé template lays out on A4 or Letter.

## 7. Deploy

```bash
npm run build
```

Vite writes a static site to `dist/`. Upload it to any static host: Netlify, Cloudflare Pages, Vercel or GitHub Pages. For GitHub Pages under `/<repo>/`, set `base: "/<repo>/"` in `vite.config.ts`. In Next.js, deploy the project as usual.

That's it. From here, browse the [components](https://www.parthjadhav.com/products/portfolio-kit/components) for sections to add, or read [Customization](https://www.parthjadhav.com/products/portfolio-kit/docs/customization) to change the markup.


---

# Theming

> Make your own theme in the builder, the tokens behind it, dark mode, and several themes on one site.

Every component reads its look from CSS variables: the standard shadcn/ui tokens plus a few kit tokens. A theme is a set of values for those variables. Change them and everything restyles at once, down to corner radius, fonts and heading weight.

There are no preset themes to install. Without any changes, you get a neutral default with a blue accent. To make it yours, use the [theme builder](https://www.parthjadhav.com/products/portfolio-kit/themes).

## The theme builder

Start from one of a few **starting points** (Default, Editorial, Swiss, Studio, Terminal), then pick an accent, neutrals, button style, heading and body fonts, radius, shadows and borders. The builder works out both palettes, light and dark, and keeps text readable (WCAG contrast) whatever you choose. While you work, this whole site and every live preview switch to your theme, so you can browse the kit in it. Previews show components or whole templates.

**Shuffle** picks a random combination to explore from. **Undo** and **Redo** (⌘Z / ⇧⌘Z) step through your changes; dragging a slider counts as one step. **Reset** goes back to the default.

When you like it, the builder gives you three ways to use it:

- **CSS**: replace the `:root` and `.dark` blocks in your global stylesheet with the generated ones.
- **shadcn CLI**: download `theme.json`, then run `npx shadcn@latest add ./theme.json`. The CLI writes the variables into your CSS.
- **Prompt**: paste the instructions into your coding agent.

The builder also lists the font packages to install (self-hosted with `@fontsource`) and the import lines to add. **Copy link** saves the theme in a URL, for example `/themes?a=38&n=paper&h=instrument-serif`. [/themes.md](https://www.parthjadhav.com/products/portfolio-kit/themes.md) lists every parameter.

## Dark mode

Dark palettes use the `.dark` class, like shadcn/ui. `ThemeToggle` manages it (light, dark or system) and remembers the choice. To force a dark surface inside a light page (a terminal window, a footer), add `className="dark"` to that element.

## Several themes on one site

Your main theme lives on `:root`. To let visitors switch between looks, scope the others with a `data-theme` attribute and use the `ThemePicker` component. A scoped theme only needs the variables it changes:

```css
[data-theme="paper"] {
  --background: oklch(0.975 0.01 80);
  --foreground: oklch(0.2 0.02 60);
  --highlight: oklch(0.55 0.13 38);
  --highlight-ink: oklch(0.55 0.13 38);
  --font-heading: "Instrument Serif", serif;
  --heading-weight: 400;
}
```

```tsx
<ThemePicker themes={[{ value: "default", label: "Default" }, { value: "paper", label: "Paper" }]} storageKey="theme" />
```

## Tokens

The shadcn/ui tokens (`background`, `foreground`, `card`, `muted`, `primary`, `border`, `ring`…) plus:

| Token | Used for |
| --- | --- |
| `--highlight` / `--highlight-foreground` | The accent as a **fill**: dots, active pills, badges, selection. |
| `--highlight-ink` | The accent as **text** on the page background (index numbers, hover links). Kept at 4.5:1 or more. |
| `--success` | Availability dots and positive states. |
| `--card-shadow` | Card elevation: none, soft, or a hard offset shadow. |
| `--font-body`, `--font-heading`, `--font-code` | Font families. |
| `--heading-weight`, `--heading-tracking` | Heading style, applied by the `font-heading` utility. |
| `--display-scale` | Optional multiplier for display-size headings (default 1): `typography.display`, `HeroStatementHeading` and the templates' hero titles. The builder sets `0.8` for monospace heading fonts, whose wider letters overflow the default scale. |
| `--radius` | Base radius. `rounded-pill` scales with it and turns square at `0`. |

In Tailwind they're available as `bg-highlight`, `text-highlight-ink`, `border-border-hover` (the border mixed toward the text color), `shadow-card`, `font-heading` and `rounded-pill`.

## Editing by hand

If you tune the variables yourself:

- Keep `--highlight-ink` at 4.5:1 or more against `--background`. If your highlight is a light fill (lime, yellow), make the ink a darker shade of it.
- Keep `--muted-foreground` at 4.5:1 or more against `--background` and `--card`.
- Use one heading family and one body family. Set `--heading-weight` to 400 for display serifs and 600–700 for grotesks.


---

# Customization

> Compose parts, restyle anything with className, pick variants, and edit the source.

## Compose parts

Most components are **compound**: a root plus named parts. Use the parts you need, in the order you want, and put anything else in between.

```tsx
<ProjectCard href="/work/lumen" variant="minimal">
  <ProjectCardMedia>
    <img src="/lumen.jpg" alt="" />
  </ProjectCardMedia>
  <ProjectCardContent>
    <ProjectCardMeta>
      <span>2025</span>
      <span>Design lead</span>
    </ProjectCardMeta>
    <ProjectCardTitle>Lumen</ProjectCardTitle>
    <ProjectCardDescription>A design system for eleven products.</ProjectCardDescription>
  </ProjectCardContent>
</ProjectCard>
```

List-like components also take data (`tags={[…]}`, `items={[…]}`) for the common case. When you need more control, render the parts yourself.

## Restyle with className

Every part accepts `className`. It's merged last with `cn()`, so your classes win:

```tsx
<ProjectCardTitle className="text-3xl">Lumen</ProjectCardTitle>
```

Every part also forwards the rest of its props (`id`, `aria-*`, event handlers, `style`) to its DOM element.

## Variants

Components with more than one visual style take a `variant` (and sometimes `size`) prop. The class recipes are exported too, e.g. `projectCardVariants`, so you can reuse them on your own elements.

## Target parts with data-slot

Each part renders a `data-slot` attribute (`data-slot="project-card-title"`). Style a part from a parent without touching the component:

```tsx
<div className="[&_[data-slot=project-card-title]]:text-highlight-ink">…</div>
```

## Links and routers

Components render plain `<a>` elements. To use your router's link, wrap the component or pass `onNavigate` where offered (`CommandMenu`). Components that accept `asChild` (like `ArrowLink`) render your element instead:

```tsx
<ArrowLink asChild>
  <Link href="/about">About me</Link>
</ArrowLink>
```

## Motion

Entrance and pointer effects respect `prefers-reduced-motion`. Durations and easing use the kit's `ease-smooth` curve. To tone motion down globally, remove the effect components you don't want, or pass `animate={false}` where offered.

## Print

Pages print cleanly without extra work. Entrance effects (`Reveal`, `TextReveal`, `Terminal`, `NumberTicker`, `ScrambleText`) print their final state even if they never scrolled into view, and the `Preloader` is hidden. Add Tailwind's `print:` variants for anything else, e.g. `print:hidden` on a header.

## Remembered state on server-rendered pages

A few components remember a visitor's choice in browser storage. The server can't read it, so on server-rendered pages (Next.js) the first paint shows the default until the page hydrates. Each one exports an optional inline script that applies the stored choice before that first paint. Add the ones you use to `<head>` in your root layout:

```tsx
import { createPreloaderScript } from "@/components/portfolio/preloader"

// inside <head>, with the same key you pass to <Preloader once storageKey="…" />
<script dangerouslySetInnerHTML={{ __html: createPreloaderScript("creative-intro") }} />
```

| Component | Script | Without it |
| --- | --- | --- |
| `ThemeToggle` | `colorModeScript` (or `createColorModeScript(storageKey)`; also add `suppressHydrationWarning` to `<html>`) | The wrong color mode flashes |
| `Preloader` with `once` | `createPreloaderScript(storageKey)` | The curtain flashes for visitors who already saw the intro |
| `AnnouncementBar` with `storageKey` | `createAnnouncementBarScript(storageKey)` | A dismissed bar flashes |
| `ContactBar` with `storageKey` | `createContactBarScript(storageKey)` | A dismissed bar flashes |

If storage is blocked, the scripts do nothing and the component shows its default.

## Match the kit in your own components

When you write your own sections, reuse the same conventions so they sit naturally next to kit components:

- **Type**: the recipes in `@/lib/typography` (`typography.title`, `typography.eyebrow`, `typography.meta`…). Small labels are the mono `eyebrow` style.
- **Cards**: `rounded-2xl border bg-card shadow-card` with `p-5 md:p-6`; linked cards lift by `-translate-y-1` on hover.
- **Pills**: `rounded-pill`, `h-8` for labels, `size-9` for icon buttons, `h-11` for main actions. Arrow chips are `size-7` with a `size-3.5` arrow.
- **Rows**: divided with `border-b`, `py-5 md:py-6`.
- **Links in text**: underline at `decoration-foreground/30`, turning `decoration-highlight-ink` on hover.
- **Motion**: `ease-smooth`, 200–300ms for hover, 500–800ms for entrances, always behind `motion-safe:` or with a `motion-reduce:` fallback.

## Edit the source

It's your code. Change the markup, add props, delete parts. Later `shadcn add` runs will ask before overwriting a file you changed.


---

# AI & agents

> Markdown versions of every page, llms.txt, the shadcn MCP server and rules to paste into your AGENTS.md.

Guides, individual component and template pages, and the theme reference are available as plain Markdown. Coding agents can read them and install source through the shadcn registry.

## Markdown for every page

Add `.md` to an individual guide, component or template URL to read its Markdown. The introduction at `/docs` uses `/docs/introduction.md`; component and template catalog pages are indexed by `/llms.txt`.

| URL | Contents |
| --- | --- |
| [`/AGENTS.md`](https://www.parthjadhav.com/products/portfolio-kit/AGENTS.md) | Integration instructions: inspect the consumer, install, preserve accessibility and verify. |
| [`/agent.md`](https://www.parthjadhav.com/products/portfolio-kit/agent.md) | Compact product scope and availability summary. |
| [`/llms.txt`](https://www.parthjadhav.com/products/portfolio-kit/llms.txt) | Index of every guide, template and component, one line each ([llmstxt.org](https://llmstxt.org) format). |
| [`/llms-full.txt`](https://www.parthjadhav.com/products/portfolio-kit/llms-full.txt) | All guides and component docs in one file. |
| `/components/<name>.md` | One component: install, usage, examples, API. |
| `/templates/<name>.md` | One template: install, the components it uses, source. |
| `/r/<name>.json` | The shadcn registry item (source files + dependencies). |

Every page also has a **Copy page** button that copies its Markdown for pasting into a chat.

## shadcn MCP server

The [shadcn MCP server](https://ui.shadcn.com/docs/mcp) lets agents browse, search and install from any registry in your `components.json`. After [adding the registry](https://www.parthjadhav.com/products/portfolio-kit/docs/installation):

```bash
npx shadcn@latest mcp init --client claude
```

Other clients: `cursor`, `vscode`, `codex`. Then ask things like *"Add a hero, a project grid and a contact section from @portfolio-kit"*.

## Rules for AGENTS.md

Paste this into your project's `AGENTS.md` (or `CLAUDE.md`, `.cursor/rules`) so your agent uses the kit correctly:

```md
## Portfolio Kit

UI for this portfolio comes from Portfolio Kit (shadcn registry `@portfolio-kit`).
- Catalog: https://www.parthjadhav.com/products/portfolio-kit/llms.txt. Read a component's docs at https://www.parthjadhav.com/products/portfolio-kit/components/<name>.md before using it.
- Install with `npx shadcn@latest add @portfolio-kit/<name>`. Files land in components/portfolio/.
- Prefer composing kit components over writing new ones. Use compound parts; restyle with className.
- Colors: semantic tokens only (bg-background, text-muted-foreground, bg-highlight, text-highlight-ink,
  border-border-hover). Never hard-code colors. Headings use font-heading; never add font-bold to them.
- Wrap page sections in <Section> (from section.tsx). Cards: rounded-2xl border bg-card shadow-card p-5 md:p-6.
- Type: use the recipes in lib/typography (typography.title, .eyebrow for small mono labels, .meta for dates).
- Motion: ease-smooth, behind motion-safe:/motion-reduce:. Content must never stay hidden (no JS, reduced motion, print).
- Keep everything accessible: real links/buttons, alt text, aria-label on icon-only buttons.
```

## Example prompts

- *"Read https://www.parthjadhav.com/products/portfolio-kit/llms.txt. Build my portfolio with the Developer template, replace the content with mine (below) and use the theme from this link: https://www.parthjadhav.com/products/portfolio-kit/themes?a=38&n=paper&h=instrument-serif&w=400."*
- *"Add a testimonials section using @portfolio-kit/testimonial-card in a three-column grid under the projects."*
- *"Read https://www.parthjadhav.com/products/portfolio-kit/components/case-study-section.md and turn this Notion export into a case study page."*

## For contributors

The repository and product `AGENTS.md` files describe maintenance boundaries. Run checks from `website/` with Bun:

```bash
bun test tests/portfolio-kit-agent-resources.test.mjs tests/portfolio-kit-release.test.mjs
bun run verify flows portfolio-kit-theme portfolio-kit-docs --origin http://localhost:3481
```

Start that local server with `bun dev -p 3481` (Portfolio Kit is on by default; `DISABLE_PORTFOLIO_KIT=1` turns it off). The parent website's `bun run verify check` runs its full release gate, including the production checks that Portfolio Kit's routes, registry and resources are served. The standalone upstream project's pnpm scripts are not commands for this native migration.


---

# Theme builder

> There are no preset themes. A theme is a set of CSS variables; make one in the theme builder and paste its CSS into your global stylesheet. Every component and template reads the same variables.

Open it: https://www.parthjadhav.com/products/portfolio-kit/themes. Changes apply to the whole docs site as you make them, so you can browse every component in your theme.

## Options

The builder derives both palettes (light and dark) from a few choices, with WCAG contrast guaranteed. Share a theme as a URL: `/themes?` plus any of these parameters (omitted = default).

| Param | Setting | Values | Default |
| --- | --- | --- | --- |
| `a` | Accent hue | 0–359 (named: red 25, orange 45, amber 75, lime 125, green 150, teal 185, sky 230, blue 262, violet 290, pink 350) | `262` |
| `i` | Accent intensity | `soft`, `bold` | `bold` |
| `n` | Neutrals | `neutral`, `stone`, `paper`, `slate`, `sage`, `mauve` | `neutral` |
| `p` | Button fill | `ink`, `accent` | `ink` |
| `r` | Radius (rem) | `0`, `0.25`, `0.5`, `0.75`, `1`, `1.25` | `0.75` |
| `h` | Heading font | `geist` (Geist), `inter` (Inter), `dm-sans` (DM Sans), `space-grotesk` (Space Grotesk), `sora` (Sora), `bricolage` (Bricolage Grotesque), `instrument-serif` (Instrument Serif), `fraunces` (Fraunces), `jetbrains-mono` (JetBrains Mono), `system` (System UI), `system-serif` (System serif) | `geist` |
| `b` | Body font | `geist` (Geist), `inter` (Inter), `dm-sans` (DM Sans), `space-grotesk` (Space Grotesk), `sora` (Sora), `jetbrains-mono` (JetBrains Mono), `system` (System UI) | `geist` |
| `c` | Code font | `geist-mono` (Geist Mono), `jetbrains-mono` (JetBrains Mono), `system-mono` (System mono) | `geist-mono` |
| `w` | Heading weight | 300–700 | `600` |
| `t` | Heading letter-spacing (em) | `-0.05`, `-0.035`, `-0.02`, `0` | `-0.035` |
| `s` | Card shadows | `none`, `subtle`, `lifted`, `hard` | `subtle` |
| `e` | Borders | `subtle`, `strong` (drawn in the text color) | `subtle` |

Example: `/themes?a=38&n=paper&r=0.25&h=instrument-serif&w=400&s=none`.

## Tokens

shadcn/ui's tokens plus the kit's: `--background`, `--foreground`, `--card`, `--card-foreground`, `--popover`, `--popover-foreground`, `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--accent-foreground`, `--destructive`, `--border`, `--input`, `--ring`, `--highlight`, `--highlight-foreground`, `--highlight-ink`, `--success`, `--card-shadow`, and `--radius`, `--font-body`, `--font-heading`, `--font-code`, `--heading-tracking`, `--heading-weight` (and `--display-scale` for monospace headings). Use `text-highlight-ink` (not `text-highlight`) for accent-colored text.

## The default theme

What you get without changing anything. Replace these blocks in your global CSS with your own, and map the fonts:

```css
:root {
  --radius: 0.75rem;
  --font-body: "Geist Variable", "Geist", ui-sans-serif, system-ui, sans-serif;
  --font-heading: "Geist Variable", "Geist", ui-sans-serif, system-ui, sans-serif;
  --font-code: "Geist Mono Variable", "Geist Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
  --heading-tracking: -0.035em;
  --heading-weight: 600;
  --background: oklch(1 0 0);
  --foreground: oklch(0.16 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.16 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.16 0 0);
  --primary: oklch(0.2 0 0);
  --primary-foreground: oklch(1 0 0);
  --secondary: oklch(0.955 0 0);
  --secondary-foreground: oklch(0.16 0 0);
  --muted: oklch(0.965 0 0);
  --muted-foreground: oklch(0.52 0 0);
  --accent: oklch(0.95 0 0);
  --accent-foreground: oklch(0.16 0 0);
  --destructive: oklch(0.577 0.245 27.3);
  --border: oklch(0.91 0 0);
  --input: oklch(0.89 0 0);
  --ring: oklch(0.57 0.21 262);
  --highlight: oklch(0.57 0.21 262);
  --highlight-foreground: oklch(1 0 0);
  --highlight-ink: oklch(0.54 0.21 262);
  --success: oklch(0.66 0.17 150);
  --card-shadow: 0 1px 2px 0 oklch(0 0 0 / 0.04), 0 2px 8px -2px oklch(0 0 0 / 0.04);
}

.dark {
  --background: oklch(0.15 0 0);
  --foreground: oklch(0.97 0 0);
  --card: oklch(0.185 0 0);
  --card-foreground: oklch(0.97 0 0);
  --popover: oklch(0.205 0 0);
  --popover-foreground: oklch(0.97 0 0);
  --primary: oklch(0.93 0 0);
  --primary-foreground: oklch(0.15 0 0);
  --secondary: oklch(0.26 0 0);
  --secondary-foreground: oklch(0.97 0 0);
  --muted: oklch(0.235 0 0);
  --muted-foreground: oklch(0.72 0 0);
  --accent: oklch(0.27 0 0);
  --accent-foreground: oklch(0.97 0 0);
  --destructive: oklch(0.704 0.191 22.2);
  --border: oklch(0.29 0 0);
  --input: oklch(0.33 0 0);
  --ring: oklch(0.74 0.134 262);
  --highlight: oklch(0.74 0.134 262);
  --highlight-foreground: oklch(0.15 0 0);
  --highlight-ink: oklch(0.74 0.134 262);
  --success: oklch(0.78 0.17 150);
  --card-shadow: 0 0 0 1px oklch(1 0 0 / 0.02), 0 8px 24px -12px oklch(0 0 0 / 0.6);
}

@theme inline {
  --font-sans: var(--font-body);
  --font-mono: var(--font-code);
}
```

See [Theming](https://www.parthjadhav.com/products/portfolio-kit/docs/theming.md) for how the tokens are used.


---

# Article template

> A single long-form post: a magazine title block, a reading column with margin sidenotes, link previews, a wide figure and a pull quote, then the author, a newsletter sign-up and related posts. Prints cleanly.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/article)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-article
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-article.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateArticle />`.

## API Reference

### TemplateArticle

The whole article page. Edit the `content` object at the top of this file to make it yours. Wire `onSubscribe` to your newsletter provider (required: without it the form only pretends to send). For your own posts, keep the layout and render your Markdown inside its `Prose` column.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSubscribe` | `(email: string) => Promise<void> \| void` | — | Called with the email from the newsletter form. Wire it to your provider. Required on a live site: without it the form only pretends to send (a preview stand-in that warns in the console). |

Also accepts every `div` prop.

## Built from

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Link Preview](https://www.parthjadhav.com/products/portfolio-kit/components/link-preview.md)
- [Newsletter Form](https://www.parthjadhav.com/products/portfolio-kit/components/newsletter-form.md)
- [Post Card](https://www.parthjadhav.com/products/portfolio-kit/components/post-card.md)
- [Prose](https://www.parthjadhav.com/products/portfolio-kit/components/prose.md)
- [Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/reveal.md)
- [Scroll Progress](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-progress.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Sidenote](https://www.parthjadhav.com/products/portfolio-kit/components/sidenote.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- [Table Of Contents](https://www.parthjadhav.com/products/portfolio-kit/components/table-of-contents.md)
- [Tag List](https://www.parthjadhav.com/products/portfolio-kit/components/tag-list.md)
- `typography` (installed with it)



---

# Case Study template

> A long-form case study page for a single project, with a facts header, chapter navigation, mockups, a before/after slider and results.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-case-study
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-case-study.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateCaseStudy />`.

## API Reference

### TemplateCaseStudy

The whole case-study page. Edit the `content` object at the top of this file to make it yours. Each chapter is a `CaseStudySection`; the table of contents links to them by id.

Also accepts every `div` prop.

## Built from

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md)
- [Before After](https://www.parthjadhav.com/products/portfolio-kit/components/before-after.md)
- [Case Study Header](https://www.parthjadhav.com/products/portfolio-kit/components/case-study-header.md)
- [Case Study Section](https://www.parthjadhav.com/products/portfolio-kit/components/case-study-section.md)
- [Color Swatches](https://www.parthjadhav.com/products/portfolio-kit/components/color-swatches.md)
- [Device Frame](https://www.parthjadhav.com/products/portfolio-kit/components/device-frame.md)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Image Gallery](https://www.parthjadhav.com/products/portfolio-kit/components/image-gallery.md)
- [Next Project](https://www.parthjadhav.com/products/portfolio-kit/components/next-project.md)
- [Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/reveal.md)
- [Scroll Progress](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-progress.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Site Footer](https://www.parthjadhav.com/products/portfolio-kit/components/site-footer.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- [Table Of Contents](https://www.parthjadhav.com/products/portfolio-kit/components/table-of-contents.md)
- [Testimonial Card](https://www.parthjadhav.com/products/portfolio-kit/components/testimonial-card.md)
- [Text Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/text-reveal.md)
- [Type Specimen](https://www.parthjadhav.com/products/portfolio-kit/components/type-specimen.md)
- `typography` (installed with it)



---

# Creative Developer template

> An award-site portfolio for a creative developer, with a short intro, smooth scrolling, a custom cursor, sideways work and a curtain footer.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/creative)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-creative
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-creative.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateCreative />`.

## API Reference

### TemplateCreative

The whole site. Edit the `content` object at the top of this file to make it yours.

Also accepts every `div` prop.

## Built from

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md)
- [Availability Badge](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge.md)
- [Copy Email](https://www.parthjadhav.com/products/portfolio-kit/components/copy-email.md)
- [Custom Cursor](https://www.parthjadhav.com/products/portfolio-kit/components/custom-cursor.md)
- [Footer Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/footer-reveal.md)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Hero Statement](https://www.parthjadhav.com/products/portfolio-kit/components/hero-statement.md)
- [Horizontal Scroll](https://www.parthjadhav.com/products/portfolio-kit/components/horizontal-scroll.md)
- [Magnetic](https://www.parthjadhav.com/products/portfolio-kit/components/magnetic.md)
- [Marquee](https://www.parthjadhav.com/products/portfolio-kit/components/marquee.md)
- [Preloader](https://www.parthjadhav.com/products/portfolio-kit/components/preloader.md)
- [Project Card](https://www.parthjadhav.com/products/portfolio-kit/components/project-card.md)
- [Project List](https://www.parthjadhav.com/products/portfolio-kit/components/project-list.md)
- [Scramble Text](https://www.parthjadhav.com/products/portfolio-kit/components/scramble-text.md)
- [Scroll Text](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-text.md)
- [Scroll Zoom](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-zoom.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Site Footer](https://www.parthjadhav.com/products/portfolio-kit/components/site-footer.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- [Smooth Scroll](https://www.parthjadhav.com/products/portfolio-kit/components/smooth-scroll.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- `typography` (installed with it)



---

# Designer template

> An image-led studio site for a designer or art director, with a big typographic intro, large project images and a short studio page.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/designer)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-designer
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-designer.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateDesigner />`.

## API Reference

### TemplateDesigner

The whole studio site. Edit the `content` object at the top of this file to make it yours. Project cards play a hover clip only when you give them one (`video` in the content, or `media.videos`). Pass `now` only to freeze the local clock in screenshots.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `now` | `Date` | — | Freeze the local clock (screenshots, tests). Omit for a live clock. |
| `media` | `TemplateDesignerMedia` | — | Media files, as URLs (public/ paths or a CDN). `videos` maps project ids to hover clips. A project without a clip (here or in its `video`) shows its artwork: no player and no network request. |

Also accepts every `div` prop.

### type TemplateDesignerMedia

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `videos` | `Partial<Record<"northpeak" \| "salt-and-signal" \| "kiln" \| "atlas-grotesk" \| "halcyon-annual", string>>` | — | Hover clips by project `id` (or `title` for a project without one), e.g. `{ "salt-and-signal": "/work/salt-and-signal.mp4" }`. Takes precedence over a project's `video`. |

## Built from

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md)
- [Availability Badge](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge.md)
- [Copy Email](https://www.parthjadhav.com/products/portfolio-kit/components/copy-email.md)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Hero Statement](https://www.parthjadhav.com/products/portfolio-kit/components/hero-statement.md)
- [Hover Video](https://www.parthjadhav.com/products/portfolio-kit/components/hover-video.md)
- [Local Time](https://www.parthjadhav.com/products/portfolio-kit/components/local-time.md)
- [Portrait](https://www.parthjadhav.com/products/portfolio-kit/components/portrait.md)
- [Project Card](https://www.parthjadhav.com/products/portfolio-kit/components/project-card.md)
- [Project List](https://www.parthjadhav.com/products/portfolio-kit/components/project-list.md)
- [Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/reveal.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- [Testimonial Card](https://www.parthjadhav.com/products/portfolio-kit/components/testimonial-card.md)
- `typography` (installed with it)



---

# Developer template

> A software engineer's site with a pinned intro and ⌘K menu on the left, and experience, projects, open source and writing on the right.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/developer)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-developer
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-developer.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateDeveloper />`.

## API Reference

### TemplateDeveloper

The whole developer site: a pinned intro column and scrolling sections. Edit the `content` object at the top of this file to make it yours. The ⌘K menu is built from the same section list.

Also accepts every `div` prop.

## Built from

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md)
- [Availability Badge](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge.md)
- [Brand Icons](https://www.parthjadhav.com/products/portfolio-kit/components/brand-icons.md)
- [Command Menu](https://www.parthjadhav.com/products/portfolio-kit/components/command-menu.md)
- [Contribution Graph](https://www.parthjadhav.com/products/portfolio-kit/components/contribution-graph.md)
- [Copy Email](https://www.parthjadhav.com/products/portfolio-kit/components/copy-email.md)
- [Experience](https://www.parthjadhav.com/products/portfolio-kit/components/experience.md)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Post List](https://www.parthjadhav.com/products/portfolio-kit/components/post-list.md)
- [Project Card](https://www.parthjadhav.com/products/portfolio-kit/components/project-card.md)
- [Repo Card](https://www.parthjadhav.com/products/portfolio-kit/components/repo-card.md)
- [Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/reveal.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- [Sticky Layout](https://www.parthjadhav.com/products/portfolio-kit/components/sticky-layout.md)
- [Theme Toggle](https://www.parthjadhav.com/products/portfolio-kit/components/theme-toggle.md)
- `typography` (installed with it)
- `use-copy-to-clipboard` (installed with it)
- [Version Label](https://www.parthjadhav.com/products/portfolio-kit/components/version-label.md)



---

# Freelancer template

> A one-person studio site that sells: a clear offer, case studies with results, services with prices, an FAQ and a contact form next to a call booker.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-freelancer
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-freelancer.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateFreelancer />`.

## API Reference

### TemplateFreelancer

The whole freelancer site. Edit the `content` object at the top of this file to make it yours. Wire `onContactSubmit` to your backend (required: without it the form only pretends to send) and point the booking card at your scheduler.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `now` | `Date` | — | Reference time for the clock and booking slots. Pass a fixed date for deterministic output. |
| `onContactSubmit` | `(data: ContactFormData) => Promise<void> \| void` | — | Wire the contact form to your backend (Formspree, a server action…). Required on a live site: without it the form only pretends to send (a preview stand-in that warns in the console). |

Also accepts every `div` prop.

### type ContactFormData

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — |  |
| `email` (required) | `string` | — |  |
| `company` (required) | `string` | — |  |
| `budget` (required) | `string` | — |  |
| `projectTypes` (required) | `string[]` | — |  |
| `message` (required) | `string` | — |  |

## Built from

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md)
- [Availability Badge](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge.md)
- [Booking Card](https://www.parthjadhav.com/products/portfolio-kit/components/booking-card.md)
- [Contact Form](https://www.parthjadhav.com/products/portfolio-kit/components/contact-form.md)
- [Dot Map](https://www.parthjadhav.com/products/portfolio-kit/components/dot-map.md)
- [FAQ](https://www.parthjadhav.com/products/portfolio-kit/components/faq.md)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Hero Intro](https://www.parthjadhav.com/products/portfolio-kit/components/hero-intro.md)
- [Local Time](https://www.parthjadhav.com/products/portfolio-kit/components/local-time.md)
- [Media](https://www.parthjadhav.com/products/portfolio-kit/components/media.md)
- [Process Steps](https://www.parthjadhav.com/products/portfolio-kit/components/process-steps.md)
- [Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/reveal.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Site Footer](https://www.parthjadhav.com/products/portfolio-kit/components/site-footer.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- [Testimonial Card](https://www.parthjadhav.com/products/portfolio-kit/components/testimonial-card.md)
- `typography` (installed with it)



---

# Links template

> A link-in-bio page for your social profiles: portrait, name and one line, availability, a stack of link buttons with one featured, your latest post, what you're listening to and a newsletter sign-up.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/links)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-links
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-links.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateLinks />`.

## API Reference

### TemplateLinks

The whole link-in-bio page, sized for phones first. Edit the `content` object at the top of this file to make it yours. Wire `onSubscribe` to your newsletter provider (required: without it the form only pretends to send).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSubscribe` | `(email: string) => Promise<void> \| void` | — | Called with the email from the newsletter form. Required on a live site: without it the form only pretends to send (a preview stand-in that warns in the console). |

Also accepts every `div` prop.

## Built from

- [Availability Badge](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge.md)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Newsletter Form](https://www.parthjadhav.com/products/portfolio-kit/components/newsletter-form.md)
- [Now Playing](https://www.parthjadhav.com/products/portfolio-kit/components/now-playing.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- [Theme Toggle](https://www.parthjadhav.com/products/portfolio-kit/components/theme-toggle.md)
- `typography` (installed with it)



---

# Minimal template

> A text-first, single-column personal site: a short intro, then quiet labelled lists of work, writing and talks.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-minimal
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-minimal.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateMinimal />`.

## API Reference

### TemplateMinimal

The whole single-column site. Edit the `content` object at the top of this file to make it yours. Wire `onSubscribe` to your newsletter provider (required: without it the form only pretends to send).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `now` | `Date` | — | Freeze the local clock (screenshots, tests). |
| `onSubscribe` | `(email: string) => Promise<void> \| void` | — | Called with the email from the newsletter form. Required on a live site: without it the form only pretends to send (a preview stand-in that warns in the console). |

Also accepts every `div` prop.

## Built from

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md)
- [Availability Badge](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge.md)
- [Copy Email](https://www.parthjadhav.com/products/portfolio-kit/components/copy-email.md)
- [Local Time](https://www.parthjadhav.com/products/portfolio-kit/components/local-time.md)
- [Newsletter Form](https://www.parthjadhav.com/products/portfolio-kit/components/newsletter-form.md)
- [Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/reveal.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- [Theme Toggle](https://www.parthjadhav.com/products/portfolio-kit/components/theme-toggle.md)
- `typography` (installed with it)
- [Version Label](https://www.parthjadhav.com/products/portfolio-kit/components/version-label.md)



---

# Not Found template

> A 404 page with some personality: a huge scrambling “404”, one honest sentence, the pages people usually want instead, and a ⌘K search to find the rest.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/not-found)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-not-found
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-not-found.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateNotFound />`.

## API Reference

### TemplateNotFound

The 404 page. Render it from your router's not-found route. Edit the `content` object at the top of this file to make it yours.

Also accepts every `div` prop.

## Built from

- [Command Menu](https://www.parthjadhav.com/products/portfolio-kit/components/command-menu.md)
- [Kbd](https://www.parthjadhav.com/products/portfolio-kit/components/kbd.md)
- [Scramble Text](https://www.parthjadhav.com/products/portfolio-kit/components/scramble-text.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- `typography` (installed with it)



---

# Photographer template

> A quiet, image-first portfolio for a photographer or filmmaker, with a featured series, a filterable index with a lightbox and a short bio.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-photographer
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-photographer.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplatePhotographer />`.

## API Reference

### TemplatePhotographer

The whole photography site. Edit the `content` object at the top of this file to make it yours. Series and filters are built from the same image list.

Also accepts every `div` prop.

## Built from

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md)
- [Availability Badge](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge.md)
- [Bio](https://www.parthjadhav.com/products/portfolio-kit/components/bio.md)
- [Copy Email](https://www.parthjadhav.com/products/portfolio-kit/components/copy-email.md)
- [Filter Chips](https://www.parthjadhav.com/products/portfolio-kit/components/filter-chips.md)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Image Gallery](https://www.parthjadhav.com/products/portfolio-kit/components/image-gallery.md)
- [Media](https://www.parthjadhav.com/products/portfolio-kit/components/media.md)
- [Portrait](https://www.parthjadhav.com/products/portfolio-kit/components/portrait.md)
- [Press List](https://www.parthjadhav.com/products/portfolio-kit/components/press-list.md)
- [Project Carousel](https://www.parthjadhav.com/products/portfolio-kit/components/project-carousel.md)
- [Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/reveal.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- `typography` (installed with it)



---

# Résumé template

> A one-page, Swiss-style CV that reads well on screen and prints cleanly to A4 or Letter: positioning, contact row, experience, selected projects, skills, education, recognition and languages.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/resume)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-resume
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-resume.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateResume />`.

## API Reference

### TemplateResume

The one-page CV, on screen and in print. Edit the `content` object at the top of this file to make it yours. Print from the browser to get A4 or Letter output.

Also accepts every `div` prop.

## Built from

- [Availability Badge](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge.md)
- [Experience](https://www.parthjadhav.com/products/portfolio-kit/components/experience.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Theme Toggle](https://www.parthjadhav.com/products/portfolio-kit/components/theme-toggle.md)
- `typography` (installed with it)



---

# Speaker template

> A site for people who mainly talk and teach: the next talk up front, every talk by year, podcast clips you can play, and a way for organisers to book you.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-speaker
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-speaker.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateSpeaker />`.

## API Reference

### TemplateSpeaker

The whole speaker site. Edit the `content` object at the top of this file to make it yours. Podcast clips get a player only once they have audio (`src` in the content, or `media.clips`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `now` | `Date` | — | Reference time for "Upcoming" badges, open booking slots and the calendar's "Now", and it freezes the local clock in the hero. Defaults to `content.updated` (the clock then runs live). |
| `media` | `TemplateSpeakerMedia` | — | Media files, as URLs (public/ paths or a CDN). `clips` maps podcast clip ids to audio files, e.g. `{ "systems-talk-61": "/audio/systems-talk-61.mp3" }`, and takes precedence over a clip's `src`. Clips without audio aren't shown; with none, the page has no player and makes no media request. |

Also accepts every `div` prop.

### type TemplateSpeakerMedia

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `clips` | `Partial<Record<"handoff-142" \| "systems-talk-61" \| "fps-30", string>>` | — | Audio by clip `id` (or `title` for a clip without one). |

## Built from

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md)
- [Audio Player](https://www.parthjadhav.com/products/portfolio-kit/components/audio-player.md)
- [Availability Badge](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge.md)
- [Availability Calendar](https://www.parthjadhav.com/products/portfolio-kit/components/availability-calendar.md)
- [Booking Card](https://www.parthjadhav.com/products/portfolio-kit/components/booking-card.md)
- [Copy Email](https://www.parthjadhav.com/products/portfolio-kit/components/copy-email.md)
- `format` (installed with it)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Hero Intro](https://www.parthjadhav.com/products/portfolio-kit/components/hero-intro.md)
- [Local Time](https://www.parthjadhav.com/products/portfolio-kit/components/local-time.md)
- [Location Tag](https://www.parthjadhav.com/products/portfolio-kit/components/location-tag.md)
- [Media](https://www.parthjadhav.com/products/portfolio-kit/components/media.md)
- [Media Appearances](https://www.parthjadhav.com/products/portfolio-kit/components/media-appearances.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Site Footer](https://www.parthjadhav.com/products/portfolio-kit/components/site-footer.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- [Talk List](https://www.parthjadhav.com/products/portfolio-kit/components/talk-list.md)
- [Testimonial Card](https://www.parthjadhav.com/products/portfolio-kit/components/testimonial-card.md)
- `typography` (installed with it)



---

# Studio template

> A small studio or agency site: a statement, a reel, stacked featured work, clients, services, awards and the team, behind a full-screen menu.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/studio)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-studio
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-studio.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateStudio />`.

## API Reference

### TemplateStudio

The whole studio site. Edit the `content` object at the top of this file to make it yours. The reel shows a still until you give it a video (`content.reel.src` or `media.reel`). Pass `now` only to freeze the local clock in screenshots.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `now` | `Date` | — | Freeze the studio clock in the hero (screenshots, tests). Omit for a live clock. |
| `media` | `TemplateStudioMedia` | — | Media files, as URLs (public/ paths or a CDN). `reel` is the showreel video. Without one (here or in `content.reel.src`) the reel shows its poster still: no player and no network request. |

Also accepts every `div` prop.

### type TemplateStudioMedia

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `reel` | `string` | — | Video URL for the reel. Takes precedence over `content.reel.src`. |

## Built from

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md)
- [Availability Badge](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge.md)
- [Availability Calendar](https://www.parthjadhav.com/products/portfolio-kit/components/availability-calendar.md)
- [Awards List](https://www.parthjadhav.com/products/portfolio-kit/components/awards-list.md)
- [Contact CTA](https://www.parthjadhav.com/products/portfolio-kit/components/contact-cta.md)
- [Copy Email](https://www.parthjadhav.com/products/portfolio-kit/components/copy-email.md)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Hero Statement](https://www.parthjadhav.com/products/portfolio-kit/components/hero-statement.md)
- [Hero Video](https://www.parthjadhav.com/products/portfolio-kit/components/hero-video.md)
- [Local Time](https://www.parthjadhav.com/products/portfolio-kit/components/local-time.md)
- [Logo Cloud](https://www.parthjadhav.com/products/portfolio-kit/components/logo-cloud.md)
- [Media](https://www.parthjadhav.com/products/portfolio-kit/components/media.md)
- [Overlay Menu](https://www.parthjadhav.com/products/portfolio-kit/components/overlay-menu.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Service List](https://www.parthjadhav.com/products/portfolio-kit/components/service-list.md)
- [Site Footer](https://www.parthjadhav.com/products/portfolio-kit/components/site-footer.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- [Stacked Cards](https://www.parthjadhav.com/products/portfolio-kit/components/stacked-cards.md)
- `typography` (installed with it)



---

# Uses template

> A quiet side page for a developer's site: what I'm doing now, the hardware, software and desk I use, what I'm reading and listening to, the sites I follow and a short page history.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/uses)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-uses
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-uses.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateUses />`.

## API Reference

### TemplateUses

The whole /uses + /now page. Edit the `content` object at the top of this file to make it yours.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `now` | `Date` | — | Reference time for relative dates ("2 hours ago"). Defaults to `page.asOf` in the content, so the page renders the same everywhere. |

Also accepts every `div` prop.

## Built from

- [Blogroll](https://www.parthjadhav.com/products/portfolio-kit/components/blogroll.md)
- [Bookshelf](https://www.parthjadhav.com/products/portfolio-kit/components/bookshelf.md)
- [Changelog](https://www.parthjadhav.com/products/portfolio-kit/components/changelog.md)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Kbd](https://www.parthjadhav.com/products/portfolio-kit/components/kbd.md)
- [Now](https://www.parthjadhav.com/products/portfolio-kit/components/now.md)
- [Now Playing](https://www.parthjadhav.com/products/portfolio-kit/components/now-playing.md)
- [Prose](https://www.parthjadhav.com/products/portfolio-kit/components/prose.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Site Footer](https://www.parthjadhav.com/products/portfolio-kit/components/site-footer.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- [Tool Grid](https://www.parthjadhav.com/products/portfolio-kit/components/tool-grid.md)
- [Version Label](https://www.parthjadhav.com/products/portfolio-kit/components/version-label.md)



---

# Writer template

> A warm, editorial home for an essayist or newsletter author: a masthead with sign-up, the latest letter and recent essays, a book spread, a reading shelf, talks and a closing subscribe band.

Follows your theme (colors, fonts, radius), in light and dark. [Live preview](https://www.parthjadhav.com/products/portfolio-kit/templates/writer)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/template-writer
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/template-writer.tsx` — a complete page. Edit the `content` object at the top of the file to make it yours, then render `<TemplateWriter />`.

## API Reference

### TemplateWriter

The whole writer's home page. Edit the `content` object at the top of this file to make it yours. Wire `onSubscribe` to your newsletter provider; both sign-up forms use it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `now` | `Date` | — | Reference date for "Upcoming" talk badges. Pass a fixed date for deterministic output. |
| `onSubscribe` | `(email: string) => Promise<void> \| void` | — | Called with the email from either sign-up form. Wire it to your newsletter provider. |

Also accepts every `div` prop.

## Built from

- [Arrow Link](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link.md)
- [Bookshelf](https://www.parthjadhav.com/products/portfolio-kit/components/bookshelf.md)
- [Generative Art](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art.md)
- [Newsletter Form](https://www.parthjadhav.com/products/portfolio-kit/components/newsletter-form.md)
- [Now](https://www.parthjadhav.com/products/portfolio-kit/components/now.md)
- [Portrait](https://www.parthjadhav.com/products/portfolio-kit/components/portrait.md)
- [Post Card](https://www.parthjadhav.com/products/portfolio-kit/components/post-card.md)
- [Post List](https://www.parthjadhav.com/products/portfolio-kit/components/post-list.md)
- [Press List](https://www.parthjadhav.com/products/portfolio-kit/components/press-list.md)
- [Reveal](https://www.parthjadhav.com/products/portfolio-kit/components/reveal.md)
- [Section](https://www.parthjadhav.com/products/portfolio-kit/components/section.md)
- [Site Footer](https://www.parthjadhav.com/products/portfolio-kit/components/site-footer.md)
- [Site Header](https://www.parthjadhav.com/products/portfolio-kit/components/site-header.md)
- [Social Links](https://www.parthjadhav.com/products/portfolio-kit/components/social-links.md)
- [Stats](https://www.parthjadhav.com/products/portfolio-kit/components/stats.md)
- [Tag List](https://www.parthjadhav.com/products/portfolio-kit/components/tag-list.md)
- [Talk List](https://www.parthjadhav.com/products/portfolio-kit/components/talk-list.md)
- [Testimonial Card](https://www.parthjadhav.com/products/portfolio-kit/components/testimonial-card.md)
- `typography` (installed with it)



---

# Announcement Bar

> Slim banner above the header for launches and availability. Static, accent-filled or scrolling, with an optional close button that can be remembered.

Category: Layout · Registry item: `@portfolio-kit/announcement-bar` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/announcement-bar) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/announcement-bar.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/announcement-bar
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/announcement-bar.tsx` and the kit items it uses: `marquee`, `use-isomorphic-layout-effect`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  AnnouncementBar,
  AnnouncementBarBadge,
  AnnouncementBarLink,
} from "@/components/portfolio/announcement-bar"

<AnnouncementBar dismissible storageKey="launch-fieldnote">
  <AnnouncementBarBadge>New</AnnouncementBarBadge>
  <span>The Fieldnote case study is live</span>
  <AnnouncementBarLink href="/work/fieldnote">Read it</AnnouncementBarLink>
</AnnouncementBar>
```

## Examples

### Demo

A slim, dismissible banner above the header for launches, new case studies or talks.

```tsx
import {
  AnnouncementBar,
  AnnouncementBarBadge,
  AnnouncementBarLink,
} from "@/components/portfolio/announcement-bar"
import { Container } from "@/components/portfolio/section"
import { SiteHeader, SiteHeaderBrand, SiteHeaderLink, SiteHeaderNav } from "@/components/portfolio/site-header"
import { typography } from "@/lib/typography"

export default function AnnouncementBarDemo() {
  return (
    <div>
      <AnnouncementBar dismissible>
        <AnnouncementBarBadge>New</AnnouncementBarBadge>
        <span>The Fieldnote case study is live</span>
        <AnnouncementBarLink href="#fieldnote">Read it</AnnouncementBarLink>
      </AnnouncementBar>
      <SiteHeader size="default">
        <SiteHeaderBrand href="#top">Noa Vale</SiteHeaderBrand>
        <SiteHeaderNav>
          <SiteHeaderLink href="#work" active>
            Work
          </SiteHeaderLink>
          <SiteHeaderLink href="#about">About</SiteHeaderLink>
          <SiteHeaderLink href="#contact">Contact</SiteHeaderLink>
        </SiteHeaderNav>
      </SiteHeader>
      <Container className="flex flex-col gap-4 pt-16 pb-20 md:pt-24 md:pb-28">
        <p className={typography.eyebrow}>Design engineer · Lisbon</p>
        <h1 className={typography.title}>Calm, fast interfaces for ambitious product teams.</h1>
      </Container>
    </div>
  )
}
```

### Highlight

Fill the bar with the theme accent for time-sensitive messages, such as open booking slots.

```tsx
import {
  AnnouncementBar,
  AnnouncementBarLink,
  AnnouncementBarText,
} from "@/components/portfolio/announcement-bar"

export default function AnnouncementBarHighlight() {
  return (
    <div>
      <AnnouncementBar variant="highlight" dismissible>
        <span>
          Booking projects for Q1 2026 <AnnouncementBarText>· two slots left</AnnouncementBarText>
        </span>
        <AnnouncementBarLink href="#contact">Get in touch</AnnouncementBarLink>
      </AnnouncementBar>
      <div className="flex flex-col gap-4 px-5 pt-16 pb-20 sm:px-8 md:pt-24">
        <p className="font-mono text-xs tracking-[0.16em] text-muted-foreground uppercase">Design engineer · Lisbon</p>
        <p className="max-w-2xl font-heading text-3xl leading-[1.1] text-balance md:text-5xl">
          Calm, fast interfaces for ambitious product teams.
        </p>
      </div>
    </div>
  )
}
```

### Marquee

An inverted, scrolling ticker with a pause button. It also pauses on hover and while its link has focus, and stands still under reduced motion.

```tsx
import { AnnouncementBar, AnnouncementBarLink } from "@/components/portfolio/announcement-bar"

export default function AnnouncementBarMarquee() {
  return (
    <div>
      <AnnouncementBar variant="marquee" duration={36} label="Availability">
        <span className="font-mono text-xs font-medium tracking-[0.16em] uppercase">Available for freelance</span>
        <span aria-hidden className="opacity-50">
          /
        </span>
        <span className="font-mono text-xs font-medium tracking-[0.16em] uppercase">Lisbon, Portugal</span>
        <span aria-hidden className="opacity-50">
          /
        </span>
        <AnnouncementBarLink href="#contact" className="font-mono text-xs font-medium tracking-[0.16em] uppercase">
          Start a project
        </AnnouncementBarLink>
      </AnnouncementBar>
      <div className="flex flex-col gap-4 px-5 pt-16 pb-20 sm:px-8 md:pt-24">
        <p className="font-mono text-xs tracking-[0.16em] text-muted-foreground uppercase">Design engineer · Lisbon</p>
        <p className="max-w-2xl font-heading text-3xl leading-[1.1] text-balance md:text-5xl">
          Calm, fast interfaces for ambitious product teams.
        </p>
      </div>
    </div>
  )
}
```

## API Reference

### AnnouncementBar

A full-width banner, a named region (`label`). Render it directly before your `SiteHeader` (as its sibling): then only the bar pads for the notch. Children are laid out
in one centered row that wraps on small screens. It pads for the notch (`env(safe-area-inset-*)`)
and isn't printed. After the close button is pressed it collapses (instantly under reduced motion).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "highlight" \| "marquee" \| null` | `"default"` | `default` is a quiet muted strip, `highlight` fills it with the theme accent, `marquee` inverts it and scrolls the content, with a pause button (it also pauses on hover and while a link is focused). Under reduced motion the marquee shows its content once, still and centered. |
| `dismissible` | `boolean` | `false` | Show a close button. |
| `storageKey` | `string` | — | Remember the dismissal in `localStorage` under this key, so the bar stays closed on the next visit. Change the key to show a new announcement. If storage is blocked, the bar simply shows again next time. On server-rendered pages, add `createAnnouncementBarScript(storageKey)` to `<head>` so a dismissed bar doesn't show for a moment before the page hydrates. |
| `onDismiss` | `() => void` | — | Called after the close button is pressed. |
| `duration` | `number` | `30` | Seconds per loop for the `marquee` variant. Lower is faster. |
| `label` | `string` | `"Announcement"` | Accessible name of the region, e.g. "Availability". |
| `dismissLabel` | `string` | `"Dismiss announcement"` | Accessible name of the close button. |
| `pauseLabel` | `string` | `"Pause announcement"` | Accessible name of the `marquee` variant's pause button (a toggle: pressed while paused). |

Also accepts every `section` prop.

### AnnouncementBarBadge

Small pill before the message, e.g. "New", "Hiring", "v2". Filled with the accent on the default bar.

Also accepts every `span` prop.

### AnnouncementBarText

Secondary text, set in a lighter weight.

Also accepts every `span` prop.

### AnnouncementBarLink

The call to action: an underlined link with a trailing arrow that nudges on hover. With
`target="_blank"` the arrow points up and out, and screen readers hear `newTabLabel`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added when the link opens in a new tab (`target="_blank"`). Translate it here. |

Also accepts every `a` prop.



---

# Archive Table

> Sortable table of every project (year, name, client, stack and link), grouped by year, with columns that collapse on small screens.

Category: Work · Registry item: `@portfolio-kit/archive-table` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/archive-table) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/archive-table.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/archive-table
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/archive-table.tsx` and the kit items it uses: `typography`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { ArchiveTable } from "@/components/portfolio/archive-table"
```

## Examples

### Demo

A sortable index of every project, grouped by year, with the stack and live link in each row.

```tsx
import { ArchiveTable, type ArchiveProject } from "@/components/portfolio/archive-table"

const archive: ArchiveProject[] = [
  {
    year: 2025,
    title: "Lumen",
    href: "#lumen",
    madeAt: "Halcyon Labs",
    builtWith: ["React", "Tokens"],
    link: "https://lumen.example.com",
  },
  {
    year: 2025,
    title: "Tidewater",
    href: "#tidewater",
    madeAt: "Tidewater Energy",
    builtWith: ["Data viz", "D3"],
    link: "https://tidewater.example.com",
  },
  {
    year: 2024,
    title: "Fieldnote",
    href: "#fieldnote",
    madeAt: "Fieldnote Inc.",
    builtWith: ["Next.js", "Motion"],
    link: "https://fieldnote.example.com",
  },
  {
    year: 2024,
    title: "Night Market posters",
    madeAt: "Side project",
    builtWith: ["Generative", "Canvas"],
  },
  {
    year: 2023,
    title: "Paperplane",
    href: "#paperplane",
    madeAt: "Open source",
    builtWith: ["TypeScript", "Animation"],
    link: "https://github.example.com/paperplane",
    linkLabel: "github.example.com",
  },
]

export default function ArchiveTableDemo() {
  return (
    <div className="mx-auto w-full max-w-5xl">
      <ArchiveTable projects={archive} />
    </div>
  )
}
```

### Minimal

Year, title and link only, with sorting off. Suits a short list of selected work.

```tsx
import { ArchiveTable, type ArchiveProject } from "@/components/portfolio/archive-table"

const selected: ArchiveProject[] = [
  { year: 2025, title: "Lumen design system", href: "#lumen", link: "https://lumen.example.com" },
  { year: 2024, title: "Orbit Analytics", href: "#orbit", link: "https://orbit.example.com" },
  { year: 2023, title: "Kiln storefront", href: "#kiln", link: "https://kiln.example.com" },
  { year: 2022, title: "Atlas & Co rebrand", href: "#atlas", link: "https://atlas.example.com" },
]

export default function ArchiveTableMinimal() {
  return (
    <ArchiveTable
      projects={selected}
      columns={["year", "project", "link"]}
      sortable={[]}
      caption="Selected projects"
      className="w-full max-w-lg"
    />
  )
}
```

### In a Section

A full archive section: a header with the project count, then client work, open source and experiments under custom column labels.

```tsx
import { ArchiveTable, type ArchiveProject } from "@/components/portfolio/archive-table"
import {
  Section,
  SectionContent,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const archive: ArchiveProject[] = [
  {
    year: 2025,
    title: "Lumen",
    href: "#lumen",
    madeAt: "Halcyon Labs",
    builtWith: ["React", "Tokens"],
    link: "https://lumen.example.com",
  },
  {
    year: 2025,
    title: "Tokens CLI",
    madeAt: "Halcyon Labs",
    builtWith: ["Node", "TypeScript"],
    link: "https://github.example.com/tokens-cli",
    linkLabel: "github.example.com",
  },
  {
    year: 2024,
    title: "Orbit Analytics",
    href: "#orbit",
    madeAt: "Orbit",
    builtWith: ["TypeScript", "Charts"],
    link: "https://orbit.example.com",
  },
  {
    year: 2023,
    title: "Meridian patient portal",
    madeAt: "Meridian Health",
    builtWith: ["Vue", "Accessibility"],
    link: "https://meridian.example.com",
  },
  {
    year: 2022,
    title: "Colour contrast checker",
    madeAt: "Open source",
    builtWith: ["Svelte"],
    link: "https://contrast.example.com",
  },
  {
    year: 2021,
    title: "Northpeak trail maps",
    madeAt: "Northpeak",
    builtWith: ["Mapbox", "React Native"],
  },
]

export default function ArchiveTableInASection() {
  return (
    <Section>
      <SectionHeader>
        <SectionEyebrow>Archive · {archive.length} projects</SectionEyebrow>
        <SectionTitle>Everything I’ve shipped</SectionTitle>
        <SectionDescription>Client work, open source and weekend experiments since 2021.</SectionDescription>
      </SectionHeader>
      <SectionContent>
        <ArchiveTable
          projects={archive}
          labels={{ madeAt: "Client", builtWith: "Stack" }}
          caption="Project archive"
        />
      </SectionContent>
    </Section>
  )
}
```

## API Reference

### ArchiveTable

A semantic `<table>` of every project. Column headers are sort buttons (`aria-sort` reflects the
state); while sorted by year, rows are grouped under each year. "Made at" folds under the title
below `md`, the stack column appears from `lg`, and the link collapses to an icon button on phones.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `projects` (required) | `ArchiveProject[]` | — | Every project, in any order. The table sorts them. Each has a `year` and `title`, and optionally `href` (case study), `madeAt`, `builtWith` (string array), `link` (live site) and `linkLabel`. |
| `columns` | `("year" \| "project" \| "madeAt" \| "builtWith" \| "link")[]` | `["year", "project", "madeAt", "builtWith", "link"]` | Which columns to show, in order: `year`, `project`, `madeAt`, `builtWith`, `link`. |
| `labels` | `Partial<Record<"year" \| "project" \| "madeAt" \| "builtWith" \| "link", string>>` | — | Override column header labels, e.g. `{ madeAt: "Client", builtWith: "Stack" }`. |
| `groupByYear` | `boolean` | `true` | Show each year once (a rule only where the year changes) while sorted by year. |
| `sortable` | `("year" \| "project" \| "madeAt")[]` | `["year", "project", "madeAt"]` | Columns the visitor can sort by (`year`, `project`, `madeAt`). Pass `[]` to disable sorting. |
| `defaultSort` | `Sort` | `{ key: "year", direction: "descending" }` | Initial sort, e.g. `{ key: "project", direction: "ascending" }`. |
| `caption` | `React.ReactNode` | `"All projects"` | Accessible table caption (visually hidden by default). |
| `captionClassName` | `string` | — | Class for the `<caption>`, e.g. `not-sr-only` to show it. |
| `empty` | `React.ReactNode` | `"No projects yet."` | Shown when `projects` is empty. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to the live-site links, which open in a new tab. Translate it here. |

Also accepts every `table` prop.

### type ArchiveProject

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `year` (required) | `number` | — | Year the project shipped. Rows are grouped and sorted by it. |
| `title` (required) | `string` | — | Project name, rendered as the row header. |
| `href` | `string` | — | Case study or detail page. Makes the title a link. |
| `madeAt` | `string` | — | Company, client or context, e.g. "Halcyon Labs" or "Side project". |
| `builtWith` | `string[]` | — | Stack or disciplines, shown as small pills (hidden below `lg`). |
| `link` | `string` | — | Live site / repo. Opens in a new tab. |
| `linkLabel` | `string` | — | Text for `link`. Defaults to the URL's host name. |

### type Sort

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `key` (required) | `"year" \| "project" \| "madeAt"` | — |  |
| `direction` (required) | `"ascending" \| "descending"` | — |  |



---

# Arrow Link

> Text link with an animated underline and a nudging arrow, for the end of a teaser or a section action. Detects external URLs and opens them safely.

Category: Utilities · Registry item: `@portfolio-kit/arrow-link` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/arrow-link) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/arrow-link.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/arrow-link
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/arrow-link.tsx`.

npm dependencies: `class-variance-authority`, `lucide-react`, `radix-ui`.

## Usage

```tsx
import { ArrowLink, arrowLinkVariants } from "@/components/portfolio/arrow-link"
```

## Examples

### Demo

The “read more” link at the end of a teaser — the underline draws in and the arrow nudges on hover. External URLs get ↗ and open in a new tab.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { typography } from "@/lib/typography"

export default function ArrowLinkDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col items-start gap-3">
      <p className={typography.eyebrow}>Case study · 2025</p>
      <h3 className={typography.heading}>Lumen design system</h3>
      <p className={typography.body}>
        How a four-person team shipped one component platform for eleven products and 140 engineers.
      </p>
      <div className="mt-1 flex flex-wrap items-baseline gap-x-6 gap-y-2">
        <ArrowLink href="#lumen" tone="highlight">
          Read the case study
        </ArrowLink>
        <ArrowLink href="https://example.com" tone="muted">
          Live site
        </ArrowLink>
      </div>
    </div>
  )
}
```

### Variants

Three tones and three underline behaviours — pick `always` when a link must look like a link at rest, `hover` for most standalone links.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { typography } from "@/lib/typography"

const rows = [
  { label: "Default", link: <ArrowLink href="#work">View all work</ArrowLink> },
  { label: "Muted", link: <ArrowLink href="#about" tone="muted">More about me</ArrowLink> },
  { label: "Highlight", link: <ArrowLink href="#contact" tone="highlight">Start a project</ArrowLink> },
  { label: "Always underlined", link: <ArrowLink href="#writing" underline="always">Read the essay</ArrowLink> },
  { label: "No arrow", link: <ArrowLink href="#archive" arrow="none" underline="always">Browse the archive</ArrowLink> },
]

export default function ArrowLinkVariants() {
  return (
    <dl className="grid w-full max-w-sm grid-cols-[auto_1fr] items-baseline gap-x-8 gap-y-5">
      {rows.map((row) => (
        <div key={row.label} className="contents">
          <dt className={typography.meta}>{row.label}</dt>
          <dd>{row.link}</dd>
        </div>
      ))}
    </dl>
  )
}
```

### External Links

Absolute URLs are detected automatically: the arrow turns ↗ and the link opens in a new tab with a safe `rel`.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { typography } from "@/lib/typography"

const links = [
  { label: "Live site", href: "https://example.com", note: "example.com" },
  { label: "Source code", href: "https://example.com/source", note: "MIT licence" },
  { label: "Launch post", href: "https://example.com/blog/launch", note: "6 min read" },
]

export default function ArrowLinkExternal() {
  return (
    <div className="w-full max-w-sm">
      <p className={typography.eyebrow}>Project links</p>
      <ul role="list" className="mt-4 divide-y border-y">
        {links.map((link) => (
          <li key={link.href} className="flex items-baseline justify-between gap-4 py-3">
            <ArrowLink href={link.href}>{link.label}</ArrowLink>
            <span className={typography.meta}>{link.note}</span>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

### Section Action

A quiet “view all” link in a split section header — it sits on the title's baseline on desktop and drops below it on phones.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import {
  SectionActions,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

export default function ArrowLinkSectionAction() {
  return (
    <div className="mx-auto max-w-5xl py-10">
      <SectionHeader align="split">
        <div className="flex flex-col gap-4">
          <SectionEyebrow index={1}>Selected work</SectionEyebrow>
          <SectionTitle>Things I&rsquo;ve shipped lately</SectionTitle>
        </div>
        <SectionActions className="shrink-0 md:pb-1.5">
          <ArrowLink href="#archive" tone="muted">
            View all 24 projects
          </ArrowLink>
        </SectionActions>
      </SectionHeader>
    </div>
  )
}
```

## API Reference

### ArrowLink

A standalone text link with an arrow that nudges on hover: the end of a teaser, a section's
"view all", a list of project links. External URLs get ↗, a new tab and a screen-reader note.
A long label wraps with the arrow kept on its last word. Inside a sentence, use a plain
underlined `<a>` instead: ArrowLink is an inline-flex box that doesn't flow across lines with
the surrounding text, and arrows mid-sentence are noise.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"default" \| "muted" \| "highlight"` | `"default"` | Text color: `default` foreground, `muted` for secondary links, `highlight` for the one call to action in a block. |
| `underline` | `"hover" \| "always" \| "none"` | `"hover"` | `hover`: the underline draws in on hover and focus. `always`: underlined at rest (it retracts on hover), for links that must read as links without a pointer, such as an email address. `none`: only the arrow moves. |
| `arrow` | `"right" \| "up-right" \| "none"` | — | Arrow direction. Defaults to `up-right` (↗) for external links and `right` (→) otherwise. Both mirror in right-to-left text. |
| `external` | `boolean` | — | Open in a new tab with `rel="noopener noreferrer"`. Auto-detected from `href` (absolute `http(s)://` or protocol-relative URLs) when omitted. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added to links that open in a new tab. Translate it for non-English sites. |
| `asChild` | `boolean` | — | Render your router's link instead of `<a>` (e.g. Next.js `<Link>`): pass it as the only child and the arrow, underline and styles are merged onto it. |

Also accepts every `a` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)
- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)
- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md)
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Audio Player

> An inline player for podcast clips, music, voice reels and sound design: a play button, a seek slider over an optional precomputed waveform and the time, on a native audio element, with one track playing at a time.

Category: Content · Registry item: `@portfolio-kit/audio-player` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/audio-player) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/audio-player.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/audio-player
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/audio-player.tsx` and the kit items it uses: `typography`, `use-composed-refs`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  AudioPlayer,
  AudioPlayerArtist,
  AudioPlayerButton,
  AudioPlayerCover,
  AudioPlayerScrubber,
  AudioPlayerTime,
  AudioPlayerTitle,
} from "@/components/portfolio/audio-player"

<AudioPlayer src="/audio/low-tide.mp3">
  <div className="flex items-center gap-4">
    <AudioPlayerCover>
      <img src="/audio/low-tide.jpg" alt="" />
    </AudioPlayerCover>
    <div className="min-w-0 flex-1">
      <AudioPlayerTitle>Low Tide</AudioPlayerTitle>
      <AudioPlayerArtist>Ines Morrow</AudioPlayerArtist>
    </div>
    <AudioPlayerButton />
  </div>
  <AudioPlayerScrubber peaks={[0.4, 0.8, 0.6, 1, 0.5, 0.3]} />
  <AudioPlayerTime />
</AudioPlayer>
```

## Examples

### Demo

A sound designer's featured piece: cover, title and play button above a waveform you can scrub, with elapsed time and length underneath.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  AudioPlayer,
  AudioPlayerArtist,
  AudioPlayerButton,
  AudioPlayerCover,
  AudioPlayerScrubber,
  AudioPlayerTime,
  AudioPlayerTitle,
} from "@/components/portfolio/audio-player"

// Precomputed once from the file (0–1 per bar), so the browser never decodes audio to draw it.
const peaks = [0.63, 0.57, 0.91, 0.62, 0.77, 0.44, 0.7, 0.41, 0.59, 0.28, 0.59, 0.26, 0.76, 0.57, 0.88, 0.53, 0.71, 0.45, 0.68, 0.41, 0.59, 0.29, 0.62, 0.28, 0.72, 0.59, 0.9, 0.61, 0.73, 0.44, 0.68, 0.38, 0.64, 0.32, 0.54, 0.26, 0.75, 0.66, 1, 0.58, 0.8, 0.49, 0.65, 0.28, 0.39, 0.15, 0.17, 0.08]

export default function AudioPlayerDemo() {
  return (
    // Your file: in public/ ("/audio/low-tide.mp3") or on a CDN. The demo clip sits next to the docs preview.
    <AudioPlayer src="media/low-tide.mp3" className="max-w-md">
      <div className="flex items-center gap-4">
        <AudioPlayerCover>
          <GenerativeArt seed="low-tide" variant="waves" />
        </AudioPlayerCover>
        <div className="min-w-0 flex-1">
          <AudioPlayerTitle>Low Tide</AudioPlayerTitle>
          <AudioPlayerArtist>Ines Morrow · Ambient score, 2026</AudioPlayerArtist>
        </div>
        <AudioPlayerButton />
      </div>
      <div className="flex flex-col gap-2">
        <AudioPlayerScrubber peaks={peaks} />
        {/* The timeline runs left to right in every language; its readouts follow it. */}
        <div dir="ltr" className="flex justify-between">
          <AudioPlayerTime format="elapsed" />
          <AudioPlayerTime format="duration" />
        </div>
      </div>
    </AudioPlayer>
  )
}
```

### Inline clip

A compact pill for a podcast or interview clip inside an article, with the transcript linked below.

```tsx
import {
  AudioPlayer,
  AudioPlayerButton,
  AudioPlayerScrubber,
  AudioPlayerTime,
} from "@/components/portfolio/audio-player"
import { typography } from "@/lib/typography"

export default function AudioPlayerInline() {
  return (
    <article className="mx-auto flex w-full max-w-xl flex-col gap-4">
      <p className={typography.body}>
        On episode 42 of <em>Field Notes</em>, I talked about recording the harbour at 4 a.m., when the
        only sounds are rope, water and one very patient gull.
      </p>
      <div className="flex flex-col items-start gap-2">
        <AudioPlayer src="media/low-tide.mp3" variant="inline" role="group" aria-label="Field Notes, episode 42 clip">
          <AudioPlayerButton playLabel="Play clip" pauseLabel="Pause clip" />
          <AudioPlayerScrubber label="Seek clip" />
          <AudioPlayerTime />
        </AudioPlayer>
        <a
          href="#transcript"
          className="py-0.5 text-sm text-muted-foreground underline decoration-foreground/30 underline-offset-[0.2em] hover:text-highlight-ink"
        >
          Read the transcript
        </a>
      </div>
      <p className={typography.body}>
        The full conversation covers contact microphones, hydrophones and why most of the job is waiting.
      </p>
    </article>
  )
}
```

### Playlist

A reel of several cues in plain rows: one plays at a time, and the next starts when a track ends.

```tsx
import {
  AudioPlayer,
  AudioPlayerArtist,
  AudioPlayerButton,
  AudioPlayerScrubber,
  AudioPlayerTime,
  AudioPlayerTitle,
  AudioPlaylist,
  AudioPlaylistItem,
} from "@/components/portfolio/audio-player"
import { typography } from "@/lib/typography"

const cues = [
  { title: "Low Tide", detail: "Main title · Harbour Lights (2026)" },
  { title: "Engine Room", detail: "Sound design · Cargo, short film" },
  { title: "Night Ferry", detail: "Ambience · Visit Faroe campaign" },
]

export default function AudioPlayerPlaylist() {
  return (
    <div className="mx-auto flex w-full max-w-2xl flex-col gap-4">
      <h2 className={typography.eyebrow}>Selected cues</h2>
      <AudioPlaylist>
        {cues.map((cue) => (
          <AudioPlaylistItem key={cue.title}>
            {/* Every row reuses the demo clip; point each at its own file. */}
            <AudioPlayer
              src="media/low-tide.mp3"
              variant="plain"
              className="grid grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-x-4 gap-y-2"
            >
              <AudioPlayerButton size="sm" className="row-span-2 self-start" />
              <div className="min-w-0">
                <AudioPlayerTitle className="text-base md:text-base">{cue.title}</AudioPlayerTitle>
                <AudioPlayerArtist>{cue.detail}</AudioPlayerArtist>
              </div>
              <AudioPlayerTime format="duration" className="self-start pt-1" />
              <AudioPlayerScrubber className="col-span-2" />
            </AudioPlayer>
          </AudioPlaylistItem>
        ))}
      </AudioPlaylist>
    </div>
  )
}
```

## API Reference

### AudioPlayer

The player: holds a native `<audio>` (no autoplay, no browser controls) and shares its state with
the parts inside. Arrange `AudioPlayerCover`, `AudioPlayerTitle`, `AudioPlayerArtist`,
`AudioPlayerButton`, `AudioPlayerScrubber` and `AudioPlayerTime` however you like. `data-state` is
`paused`, `loading`, `playing` or `error`.

Starting one player pauses any other (`exclusive`), and nothing plays until the visitor presses
play. For speech (podcasts, interviews, voice reels) put a transcript next to the player, as a
link or an expandable section: deaf and hard-of-hearing visitors can't use the audio otherwise
(WCAG 1.2.1). The controls need JavaScript; link the file itself if the page must work without it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | — | Audio URL (MP3, AAC/M4A, Ogg, WAV). Serve it with byte-range support so seeking works. |
| `sources` | `AudioPlayerSource[]` | — | Several encodings, in order of preference (e.g. Opus, then MP3). Used instead of `src`. |
| `variant` | `"card" \| "inline" \| "plain"` | `"card"` | `card`: a bordered card for a featured track. `inline`: a compact pill that sits in running text. `plain`: no chrome, for rows in an `AudioPlaylist` or your own layout. |
| `duration` | `number` | — | Length in seconds, shown until the file's metadata loads (and with `preload="none"`, until the visitor presses play). The file's real duration replaces it. |
| `preload` | `"none" \| "metadata" \| "auto"` | `"metadata"` | How much to fetch before play. `metadata` loads only the length; `none` loads nothing until play. |
| `exclusive` | `boolean` | `true` | Pause any other kit audio player when this one starts, so only one track plays at a time. |
| `onPlayingChange` | `(playing: boolean) => void` | — | Called when playback starts or stops (including when another player takes over or the track ends). |
| `audioRef` | `React.Ref<HTMLAudioElement>` | — | Ref to the underlying `<audio>` element, for volume, playback rate or starting playback yourself. |

Also accepts every `div` prop.

### AudioPlayerCover

Square artwork: an `<img>` (cropped to fill) or `<GenerativeArt />`. Decorative, so give images
`alt=""`; the title names the track.

Also accepts every `div` prop.

### AudioPlayerTitle

Track name. The play button and the slider use it in their accessible names ("Play Low Tide").

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h2" \| "h3" \| "h4" \| "p"` | `"h3"` | Heading level (or `p` when the track name isn't a heading). |

Also accepts every `h3` prop.

### AudioPlayerArtist

Artist, show or episode line under the title.

Also accepts every `p` prop.

### AudioPlayerButton

Play/pause button, named by its action and the title ("Play Low Tide", "Pause Low Tide"). It shows
a spinner while buffering (`aria-busy`) and turns into an alert icon, `aria-disabled`, when the file
fails, keeping keyboard focus where it was. Labels are props so you can translate them.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "sm"` | `"default"` | `default` is 44 px; `sm` looks 36 px but keeps a 44 px touch area. Defaults to `sm` inside the `inline` variant. |
| `playLabel` | `string` | `"Play"` | Spoken action while paused; the title follows it ("Play Low Tide"). |
| `pauseLabel` | `string` | `"Pause"` | Spoken action while playing. |
| `unavailableLabel` | `string` | `"Audio unavailable"` | Spoken name when the file can't be played. The button stays focusable but does nothing. |

Also accepts every `button` prop.

### AudioPlayerScrubber

Seek slider (`role="slider"`), drawn as a waveform or a progress bar. Drag or click to seek;
arrows, Page Up/Down, Home and End from the keyboard. It announces "0:12 of 0:42". Like other
media timelines it runs left to right in right-to-left pages too (`dir="ltr"`), so the arrow keys,
the fill and the waveform agree.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `peaks` | `number[]` | — | Waveform bar heights from 0 to 1, precomputed from the file (40–80 values read well). Without peaks it's a thin progress bar. Generate them once at build time, e.g. with `audiowaveform` or ffmpeg; the player never decodes audio in the browser. |
| `step` | `number` | `5` | Seconds moved by the arrow keys. Page Up/Down move a tenth of the track; Home/End jump to the ends. |
| `label` | `string` | `"Seek"` | Spoken action; the title follows it ("Seek Low Tide"). |
| `valueTextLabel` | `string` | `"{elapsed} of {duration}"` | Spoken position once the length is known; `{elapsed}` and `{duration}` are replaced. Translate it with the other labels. |

Also accepts every `div` prop.

### AudioPlayerTime

Time readout in tabular mono numbers. It updates once a second and shows "–:––" while the length is unknown.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `format` | `"both" \| "elapsed" \| "remaining" \| "duration"` | `"both"` | `both`: "0:12 / 0:42". `elapsed`: "0:12". `remaining`: "-0:30". `duration`: "0:42". |
| `unavailableLabel` | `string` | `"Unavailable"` | Shown instead of the elapsed time when the file can't be played. |

Also accepts every `span` prop.

### AudioPlaylist

An ordered list of tracks, each an `AudioPlaylistItem` holding an `AudioPlayer` (usually
`variant="plain"`). Only one plays at a time.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `continuous` | `boolean` | `true` | When a track ends, start the next one in the list. |

Also accepts every `ol` prop.

### AudioPlaylistItem

One row of an `AudioPlaylist`.

Also accepts every `li` prop.

### type AudioPlayerSource

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `src` (required) | `string` | — | File URL. |
| `type` | `string` | — | MIME type, e.g. `audio/ogg` or `audio/mpeg`. Lets the browser skip formats it can't play. |

## Used in templates

- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)



---

# Aurora

> Slowly drifting gradient blobs in hues around your theme's highlight, used as a hero or card backdrop. Static under reduced motion.

Category: Effects · Registry item: `@portfolio-kit/aurora` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/aurora) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/aurora.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/aurora
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/aurora.tsx` and the kit items it uses: `use-in-view`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { Aurora, auroraVariants } from "@/components/portfolio/aurora"
```

## Examples

### Demo

A hero backdrop of slow gradient blobs in your theme's highlight hues. On a section forced to the dark palette, they glow like northern lights and fade out before the content below.

```tsx
import { cn } from "@/lib/utils"
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { Aurora } from "@/components/portfolio/aurora"
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { Section } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

export default function AuroraDemo() {
  return (
    // `dark` gives this section the theme's dark palette, where the aurora glows instead of tinting.
    <Section spacing="lg" className="dark isolate overflow-hidden bg-background text-foreground">
      <Aurora intensity="vivid" />
      <div className="flex flex-col items-start gap-6">
        <AvailabilityBadge detail="from March" />
        <h1 className={cn(typography.display, "max-w-4xl")}>
          Noa designs software that feels <em>inevitable</em>.
        </h1>
        <div className="flex w-full flex-col gap-6 sm:flex-row sm:items-end sm:justify-between sm:gap-12">
          {/* Muted gray loses contrast over the glow: tint the foreground instead. */}
          <p className={cn(typography.lead, "max-w-md text-foreground/80")}>
            Design engineer building calm, fast interfaces for ambitious product teams.
          </p>
          <ArrowLink href="#work" className="shrink-0">
            See selected work
          </ArrowLink>
        </div>
      </div>
    </Section>
  )
}
```

### Intensities

`subtle` sits behind long copy, `vivid` suits a near-empty hero. Blob count and speed tune it further.

```tsx
import { Aurora } from "@/components/portfolio/aurora"
import { typography } from "@/lib/typography"

const tiles = [
  { intensity: "subtle", note: "Behind long copy" },
  { intensity: "default", note: "Hero backdrops" },
  { intensity: "vivid", note: "Near-empty intros" },
] as const

export default function AuroraIntensities() {
  return (
    <ul role="list" className="mx-auto grid max-w-5xl gap-4 md:grid-cols-3">
      {tiles.map((tile) => (
        <li
          key={tile.intensity}
          className="relative isolate flex aspect-[4/3] flex-col justify-end gap-1 overflow-hidden rounded-2xl border bg-card p-5 shadow-card md:p-6"
        >
          <Aurora intensity={tile.intensity} fade={false} />
          <p className={typography.eyebrow}>{tile.intensity}</p>
          <p className={typography.heading}>{tile.note}</p>
        </li>
      ))}
    </ul>
  )
}
```

### In a card

Scope the glow to one surface, such as a contact card, by giving the card `relative isolate overflow-hidden`.

```tsx
import { Mail } from "lucide-react"

import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import { Aurora } from "@/components/portfolio/aurora"
import { typography } from "@/lib/typography"

export default function AuroraInACard() {
  return (
    <div className="relative isolate flex w-full max-w-md flex-col gap-8 overflow-hidden rounded-2xl border bg-card p-6 shadow-card md:p-8">
      <Aurora blobs={2} intensity="subtle" fade={false} speed={0.75} />
      <div className="flex flex-col gap-3">
        {/* Muted gray loses contrast over the glow: tint the foreground instead. */}
        <p className={cn(typography.eyebrow, "text-foreground/80")}>Now booking Q3</p>
        <h2 className={cn(typography.title, "text-3xl sm:text-4xl md:text-4xl")}>Have something in mind?</h2>
        <p className={cn(typography.body, "text-foreground/80")}>
          Tell me about the product, the team and the timeline. I reply within two working days.
        </p>
      </div>
      <a href="#contact" className={buttonVariants({ size: "lg", className: "w-fit rounded-pill" })}>
        <Mail aria-hidden />
        hello@example.com
      </a>
    </div>
  )
}
```

### Monochrome

Pass `colors` to step away from the accent. Neutral tones give a quiet grey mist that works with any palette.

```tsx
import { Aurora } from "@/components/portfolio/aurora"
import {
  Section,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const mist = [
  "color-mix(in oklab, var(--foreground) 16%, var(--background))",
  "color-mix(in oklab, var(--foreground) 9%, var(--background))",
  "color-mix(in oklab, var(--muted-foreground) 24%, var(--background))",
]

export default function AuroraMonochrome() {
  return (
    <Section spacing="lg" className="isolate overflow-hidden">
      <Aurora colors={mist} blobs={3} intensity="vivid" speed={1.5} />
      <SectionHeader>
        {/* Muted gray loses contrast over the mist: tint the foreground instead. */}
        <SectionEyebrow className="text-foreground/80">About</SectionEyebrow>
        <SectionTitle>Nine years between design and code.</SectionTitle>
        <SectionDescription className="text-foreground/80">
          I work at the seam between product design and front-end engineering — from the first sketch to the last
          millisecond of an interaction.
        </SectionDescription>
      </SectionHeader>
    </Section>
  )
}
```

### With grain

A vivid aurora under a film-grain layer. The noise breaks up gradient banding on large, flat areas of color.

```tsx
import { cn } from "@/lib/utils"
import { Aurora } from "@/components/portfolio/aurora"
import { Grain } from "@/components/portfolio/grain"
import { typography } from "@/lib/typography"

export default function AuroraWithGrain() {
  return (
    <section className="relative isolate grid min-h-[34rem] place-items-center overflow-hidden px-5 py-24 text-center">
      <Aurora intensity="vivid" />
      <Grain
        position="absolute"
        opacity={0.07}
        className="-z-[5] [mask-image:linear-gradient(to_bottom,black_40%,transparent_95%)]"
      />
      <div className="flex max-w-3xl flex-col items-center gap-5">
        {/* On a vivid backdrop, muted gray loses contrast: use the foreground (small text at full strength). */}
        <p className={cn(typography.eyebrow, "text-foreground")}>Design Engineer · Lisbon</p>
        <h1 className={typography.display}>Hello, I&rsquo;m Noa.</h1>
        <p className={cn(typography.lead, "max-w-md text-foreground/75")}>
          I design and build calm, fast interfaces for ambitious product teams.
        </p>
      </div>
    </section>
  )
}
```

## API Reference

### Aurora

Place inside a `relative isolate` parent (e.g. a hero). It fills the parent
at `-z-10`, fades out toward the bottom and ignores the pointer. The drift
pauses while the aurora is off screen, comes to rest by itself and doesn't run
under reduced motion. Hidden in print and in forced-colors mode. Small text over
the glow should use `text-foreground` (or `/80`), not `text-muted-foreground`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `intensity` | `"subtle" \| "default" \| "vivid"` | `"default"` | Overall strength: `subtle` behind long copy, `default` for heroes, `vivid` for near-empty intros. Dark mode keeps every blob in a mid-lightness band, so warm accents glow instead of turning muddy and light text stays readable. |
| `fade` | `boolean` | `true` | Fade out toward the bottom so the glow never collides with the next section. Turn off inside cards. |
| `speed` | `number` | `1` | Multiplies every drift duration: `2` is twice as slow, `0.5` twice as fast. `0` freezes the blobs. Each blob drifts out and back once (under a minute at `1`), then rests. |
| `blobs` | `1 \| 2 \| 3 \| 4` | `4` | Number of blobs (1–4). Fewer blobs leave more of the background showing. |
| `colors` | `string[]` | `defaultColors` | Override the blob colors (any CSS color, including `var(--token)`), cycled over the blobs. Defaults to the theme's highlight and its two hue neighbours. |

Also accepts every `div` prop.



---

# Availability Badge

> Status pill with a pulsing dot that says whether you're taking work, e.g. “Available for work” or “Booked until March”.

Category: Hero · Registry item: `@portfolio-kit/availability-badge` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/availability-badge) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/availability-badge.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/availability-badge
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/availability-badge.tsx`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { AvailabilityBadge, availabilityBadgeVariants, StatusDot } from "@/components/portfolio/availability-badge"
```

## Examples

### Demo

Shows whether you're taking work: a pulsing status dot, a label and an optional muted detail.

```tsx
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"

export default function AvailabilityBadgeDemo() {
  return (
    <div className="flex w-full max-w-md flex-col items-start gap-4">
      <AvailabilityBadge detail="from November">Open to projects</AvailabilityBadge>
      <p className="font-heading text-3xl leading-tight text-balance">
        Noa Vale designs and builds calm, fast interfaces.
      </p>
    </div>
  )
}
```

### Statuses

`available` pulses green, `limited` uses your highlight color, `unavailable` goes still and grey. Each has a sensible default label.

```tsx
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"

export default function AvailabilityBadgeStatuses() {
  return (
    <div className="flex flex-col items-start gap-3">
      <AvailabilityBadge status="available" />
      <AvailabilityBadge status="limited" detail="1 slot in Q1" />
      <AvailabilityBadge status="unavailable" />
    </div>
  )
}
```

### Variants

`pill` floats over heroes and media, `soft` sits inside cards, `plain` drops into meta rows and running text. With `href`, any of them links somewhere, like your contact section.

```tsx
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"

export default function AvailabilityBadgeVariants() {
  return (
    <div className="flex flex-col items-start gap-4">
      <AvailabilityBadge variant="pill">Available for work</AvailabilityBadge>
      <AvailabilityBadge variant="soft" status="limited">
        Booking for March
      </AvailabilityBadge>
      <AvailabilityBadge variant="plain" detail="from January" href="#contact">
        Taking projects
      </AvailabilityBadge>
    </div>
  )
}
```

### Over Media

The pill's translucent, blurred fill keeps it legible on top of a portrait or cover image.

```tsx
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { GenerativeArt } from "@/components/portfolio/generative-art"

export default function AvailabilityBadgeOverMedia() {
  return (
    <div className="relative aspect-[4/5] w-xs max-w-full overflow-hidden rounded-2xl border shadow-card">
      <GenerativeArt seed="badge-portrait" variant="portrait" label="Portrait of Noa" />
      <AvailabilityBadge detail="from Nov" className="absolute bottom-4 left-4">
        Available
      </AvailabilityBadge>
    </div>
  )
}
```

## API Reference

### StatusDot

The colored dot on its own, for meta rows, cards or custom badges. Resize it with a
`size-*` class (defaults to `size-2`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"available" \| "limited" \| "unavailable"` | `"available"` | Which color the dot takes: `available` (success), `limited` (highlight) or `unavailable` (muted, never pulses). |
| `pulse` | `boolean` | `true` | Emit a soft ring that pulses outward twice after the dot appears, then rests (under 5 s, so it needs no pause control under WCAG 2.2.2). Hidden when the user prefers reduced motion. |

Also accepts every `span` prop.

### AvailabilityBadge

A status dot, a label (children, or a default per `status`) and an optional muted `detail`.
`pill` floats over heroes and media, `soft` sits inside cards, `plain` drops into meta rows.
The label states the status in words; the dot's color only repeats it. Renders a `<span>`, or
an `<a>` with `href`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | Turn the badge into a link, e.g. to your contact section or booking page. It gets a focus ring and the kit's hover; external URLs open in a new tab and say so to screen readers. |
| `variant` | `"pill" \| "soft" \| "plain"` | `"pill"` | `pill`: bordered and frosted, for heroes over images or color. `soft`: a muted fill without border. `plain`: dot and text only, for inline use. |
| `ref` | `React.Ref<HTMLElement>` | — | The root element: the `<span>`, or the `<a>` when you pass `href`. |
| `status` | `"available" \| "limited" \| "unavailable"` | `"available"` | Your booking state. Sets the dot color and the default label ("Available for work", "Limited availability", "Not taking new projects"). |
| `pulse` | `boolean` | `true` | Pulse the dot twice, then rest (never when `unavailable`). Off for reduced motion. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added when `href` opens in a new tab. Translate it here. |
| `detail` | `React.ReactNode` | — | Secondary text, e.g. a date. Rendered muted after the label. |
| `truncate` | `boolean` | `false` | Keep the badge on one line and cut long text with an ellipsis. By default the text wraps when space runs out, so nothing is ever clipped. |

Also accepts every `a` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)
- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Links](https://www.parthjadhav.com/products/portfolio-kit/templates/links.md)
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md)
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)
- [Résumé](https://www.parthjadhav.com/products/portfolio-kit/templates/resume.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Availability Calendar

> The next months at a glance, each marked open, limited or booked in words and a fill pattern, so clients see when you can start.

Category: Contact · Registry item: `@portfolio-kit/availability-calendar` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/availability-calendar) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/availability-calendar.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/availability-calendar
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/availability-calendar.tsx` and the kit items it uses: `format`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  AvailabilityCalendar,
} from "@/components/portfolio/availability-calendar"

<AvailabilityCalendar
  today="2026-10-04"
  months={[
    { month: "2026-10", status: "booked" },
    { month: "2026-11", status: "limited", note: "One small project" },
    { month: "2026-12", status: "open" },
  ]}
/>
```

## Examples

### Demo

The next twelve months for a freelancer: booked through the winter, limited in spring and open from May, with this month marked "Now".

```tsx
import { AvailabilityCalendar } from "@/components/portfolio/availability-calendar"

export default function AvailabilityCalendarDemo() {
  return (
    <AvailabilityCalendar
      today="2026-10-04"
      className="w-full max-w-3xl"
      months={[
        { month: "2026-10", status: "booked" },
        { month: "2026-11", status: "booked" },
        { month: "2026-12", status: "limited" },
        { month: "2027-01", status: "booked" },
        { month: "2027-02", status: "booked" },
        { month: "2027-03", status: "limited" },
        { month: "2027-04", status: "limited" },
        { month: "2027-05", status: "open" },
        { month: "2027-06", status: "open" },
        { month: "2027-07", status: "limited" },
        { month: "2027-08", status: "booked" },
        { month: "2027-09", status: "open" },
      ]}
    />
  )
}
```

### Compact

Six months as a list inside a contact card, next to an availability badge and a call to action.

```tsx
import { ArrowUpRight } from "lucide-react"

import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { AvailabilityCalendar } from "@/components/portfolio/availability-calendar"
import { typography } from "@/lib/typography"

export default function AvailabilityCalendarCompact() {
  return (
    <div className="flex w-full max-w-md flex-col gap-6 rounded-2xl border bg-card p-5 text-card-foreground shadow-card md:p-6">
      <div className="flex flex-col items-start gap-3">
        <AvailabilityBadge status="limited" variant="soft" detail="from February" />
        <h3 className={typography.heading}>Planning something for next year?</h3>
        <p className={typography.body}>I take two clients at a time. Here&apos;s where there&apos;s room.</p>
      </div>
      <AvailabilityCalendar
        variant="list"
        today="2026-11-12"
        from="2026-11"
        count={6}
        defaultStatus="booked"
        months={[
          { month: "2027-02", status: "limited", note: "One small project" },
          { month: "2027-03", status: "open" },
          { month: "2027-04", status: "open" },
        ]}
        label="Availability, November 2026 to April 2027"
      />
      <a
        href="mailto:hello@example.com"
        className={cn(buttonVariants({ size: "lg" }), "h-11 self-start rounded-pill px-5")}
      >
        Start a project
        <ArrowUpRight aria-hidden />
      </a>
    </div>
  )
}
```

### With notes

A short note per month explains the gaps: leave, a residency, a slot that's nearly gone.

```tsx
import { AvailabilityCalendar } from "@/components/portfolio/availability-calendar"

export default function AvailabilityCalendarWithNotes() {
  return (
    <AvailabilityCalendar
      today="2027-03-02"
      className="w-full max-w-[35rem]"
      months={[
        { month: "2027-03", status: "booked", note: "Brand refresh for a studio" },
        { month: "2027-04", status: "booked", note: "Parental leave" },
        { month: "2027-05", status: "booked", note: "Parental leave" },
        { month: "2027-06", status: "limited", note: "One slot left" },
        { month: "2027-07", status: "open" },
        { month: "2027-08", status: "limited", note: "Residency in Lisbon, remote only" },
      ]}
    />
  )
}
```

## API Reference

### AvailabilityCalendar

Root. Holds the shared settings (layout, locale, today, labels) and, given `months`, renders the
month list and a legend. Any `children` go after the list. It's a container-query root, so the
grid's column count follows the slot it sits in, not the viewport. A display component: nothing
in it is interactive.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `months` | `AvailabilityMonth[]` | — | The months to show, e.g. `[{ month: "2026-11", status: "booked", note: "Parental leave" }]`. Gaps between the first and last month are filled with `defaultStatus`. Leave it out to compose `<AvailabilityCalendarMonths>` yourself. |
| `from` | `string` | — | First month shown (`"2026-10"`). Defaults to the earliest month in `months`. |
| `count` | `number` | — | How many months to show from `from`. Defaults to the range covered by `months`. |
| `defaultStatus` | `"open" \| "limited" \| "booked"` | `"open"` | Status of months inside the range that `months` doesn't mention. |
| `variant` | `"grid" \| "list"` | `"grid"` | `grid`: a tile per month (2 → 6 columns with the container width). `list`: one row per month, for narrow slots and notes. |
| `locale` | `string` | `"en-US"` | BCP 47 locale for month names and years, e.g. `"de-DE"`. Translate the status words with `labels`. |
| `today` | `DateInput \| false` | — | The date that counts as today; its month is marked "Now" with `aria-current="date"`. Pass it (e.g. your build date or `"2026-10-04"`) for identical server and client output. When left out, the current month is read from the visitor's clock after hydration, so the marker appears a moment after load. `false` turns the marker off. |
| `labels` | `Partial<AvailabilityCalendarLabels>` | — | Words for each status, the current-month marker and the legend's accessible name: `{ open, limited, booked, current, legend }`. |
| `label` | `string` | `"Availability by month"` | Accessible name of the month list. |
| `showLegend` | `boolean` | `true` | Render the legend after the months. Turn it off to place `<AvailabilityCalendarLegend>` yourself. |

Also accepts every `div` prop.

### AvailabilityCalendarMonths

The ordered list of months, laid out by the root's `variant`. The year is shown on the first
month and on each January (screen readers always hear it).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `months` | `AvailabilityMonth[]` | — | Months to render, as on the root. Without it, pass `<AvailabilityCalendarMonth>` children. |
| `from` | `string` | — | First month shown (`"2026-10"`). Defaults to the earliest month in `months`. |
| `count` | `number` | — | How many months to show from `from`. Defaults to the range covered by `months`. |
| `defaultStatus` | `"open" \| "limited" \| "booked"` | `"open"` | Status of months in range that `months` doesn't mention. |

Also accepts every `ol` prop.

### AvailabilityCalendarMonth

One month: its name in a `<time dateTime="2026-11">`, a status bar, the status in words and an
optional note. The current month gets `aria-current="date"` and a "Now" marker.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `month` (required) | `string` | — | The month, as `"2026-11"`. |
| `status` | `"open" \| "limited" \| "booked"` | `"open"` | `open`: taking work. `limited`: room for something small. `booked`: full. |
| `note` | `React.ReactNode` | — | A short note under the status, e.g. "One slot left" or "Parental leave". |
| `showYear` | `boolean` | `true` | Show the year next to the month name. When hidden it stays in the text for screen readers. |

Also accepts every `li` prop.

### AvailabilityCalendarSwatch

The status bar on its own, for legends or custom layouts. Decorative (`aria-hidden`); pair it with the status in words.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` (required) | `"open" \| "limited" \| "booked"` | `"open"` | Which pattern to draw: a full bar (`open`), a half bar (`limited`) or an empty hatched track (`booked`). |

Also accepts every `span` prop.

### AvailabilityCalendarLegend

A swatch and word per status. The root renders one (`showLegend`); use this to place it elsewhere.
Its accessible name is `labels.legend` unless you pass `aria-label`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `statuses` | `("open" \| "limited" \| "booked")[]` | `["open", "limited", "booked"]` | Statuses to explain, in order. |

Also accepts every `ul` prop.

### type AvailabilityMonth

One month of availability: `month` as `"2026-11"`, its status and an optional short note.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `month` (required) | `string` | — |  |
| `status` (required) | `"open" \| "limited" \| "booked"` | — |  |
| `note` | `React.ReactNode` | — |  |

### type AvailabilityCalendarLabels

Words for each status, the current-month marker and the legend's accessible name.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `legend` (required) | `string` | — |  |
| `limited` (required) | `string` | — |  |
| `open` (required) | `string` | — |  |
| `booked` (required) | `string` | — |  |
| `current` (required) | `string` | — |  |

## Used in templates

- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Awards List

> Awards table with award, organization, project and year per row, a “×3” count for repeat wins and an optional summary of totals.

Category: Social Proof · Registry item: `@portfolio-kit/awards-list` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/awards-list) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/awards-list.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/awards-list
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/awards-list.tsx` and the kit items it uses: `typography`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import {
  AwardItem,
  AwardsList,
  AwardsListHead,
  AwardsListHeader,
  AwardsListItems,
  AwardsListSummary,
} from "@/components/portfolio/awards-list"

<AwardsList>
  <AwardsListHeader>
    <h2>Recognition</h2>
    <AwardsListSummary stats={[{ value: 12, label: "awards" }]} />
  </AwardsListHeader>
  <AwardsListHead />
  <AwardsListItems>
    <AwardItem award="Site of the Day" organization="Awwwards" project="Fieldnote" year={2025} count={3} />
    <AwardItem award="Best Portfolio" organization="CSS Design Awards" project="Studio site" year={2024} />
  </AwardsListItems>
</AwardsList>
```

## Examples

### Demo

An awards table with a summary header: award, organization, project and year, with “×3” badges for repeat wins.

```tsx
import {
  AwardItem,
  AwardsList,
  AwardsListHead,
  AwardsListHeader,
  AwardsListItems,
  AwardsListSummary,
} from "@/components/portfolio/awards-list"
import { SectionEyebrow } from "@/components/portfolio/section"

/** Fictional award bodies and results. */
const awards = [
  { id: "sotd", award: "Site of the Day", organization: "Pixelfolk Awards", project: "Lumen", year: 2025, count: 3 },
  { id: "dev", award: "Developer Award", organization: "Pixelfolk Awards", project: "Lumen", year: 2025 },
  { id: "hm", award: "Honorable Mention", organization: "Gridline", project: "Tidewater", year: 2025, count: 2 },
  { id: "interaction", award: "Best Interaction Design", organization: "Motion Index", project: "Fieldnote", year: 2024 },
]

export default function AwardsListDemo() {
  return (
    <AwardsList className="mx-auto max-w-5xl">
      <AwardsListHeader>
        <SectionEyebrow index={5}>Recognition</SectionEyebrow>
        <AwardsListSummary
          stats={[
            { value: 12, label: "awards" },
            { value: 4, label: "SOTD" },
          ]}
        />
      </AwardsListHeader>
      <AwardsListHead />
      <AwardsListItems>
        {awards.map(({ id, ...award }) => (
          <AwardItem key={id} {...award} href={`#${id}`} />
        ))}
      </AwardsListItems>
    </AwardsList>
  )
}
```

### Plain

No links and no column head: a quiet list beside a section title on an about page.

```tsx
import { AwardItem, AwardsList, AwardsListItems } from "@/components/portfolio/awards-list"
import { Section, SectionEyebrow, SectionHeader, SectionTitle } from "@/components/portfolio/section"

const awards = [
  { award: "Site of the Month", organization: "Pixelfolk Awards", project: "Fieldnote", year: 2024 },
  { award: "Typography Honors", organization: "Type Directors Circle", project: "Kiln", year: 2023, count: 2 },
  { award: "Best Portfolio", organization: "Gridline", project: "Personal site", year: 2023 },
  { award: "Honorable Mention", organization: "Motion Index", project: "Paperplane", year: 2022 },
]

export default function AwardsListPlain() {
  return (
    <Section>
      <div className="grid gap-10 lg:grid-cols-[1fr_2fr] lg:gap-16">
        <SectionHeader>
          <SectionEyebrow>Awards</SectionEyebrow>
          <SectionTitle>A few kind nods from the industry.</SectionTitle>
        </SectionHeader>
        <AwardsList>
          <AwardsListItems>
            {awards.map((award) => (
              <AwardItem key={`${award.award}-${award.year}`} {...award} />
            ))}
          </AwardsListItems>
        </AwardsList>
      </div>
    </Section>
  )
}
```

### Film Festivals

A filmmaker’s laurels: rename the columns with `labels` and add a jury note under the award with `children`.

```tsx
import {
  AwardItem,
  AwardsList,
  AwardsListHead,
  AwardsListHeader,
  AwardsListItems,
  AwardsListSummary,
} from "@/components/portfolio/awards-list"
import { typography } from "@/lib/typography"

const festivals = [
  {
    id: "northlight",
    award: "Best Animated Short",
    organization: "Northlight Film Festival",
    project: "Tidal",
    year: 2025,
    note: "“A quiet film about the sea that somehow fills the whole room.”",
  },
  { id: "saltmarsh", award: "Official Selection", organization: "Saltmarsh Shorts", project: "Tidal", year: 2025, count: 4 },
  {
    id: "lumiere",
    award: "Audience Award",
    organization: "Lumière Nights",
    project: "Paper Moons",
    year: 2024,
    note: "Voted by 2,300 festival-goers across three screenings.",
  },
  { id: "kinetic", award: "Jury Mention", organization: "Kinetic Motion Fest", project: "Paper Moons", year: 2023 },
]

export default function AwardsListFestivals() {
  return (
    <AwardsList className="mx-auto max-w-5xl">
      <AwardsListHeader>
        <h2 className={typography.title}>Festivals</h2>
        <AwardsListSummary
          stats={[
            { value: 11, label: "selections" },
            { value: 3, label: "wins" },
          ]}
        />
      </AwardsListHeader>
      <AwardsListHead labels={["Laurel", "Festival", "Film", "Year"]} />
      <AwardsListItems>
        {festivals.map(({ id, note, ...festival }) => (
          <AwardItem key={id} {...festival} href={`https://example.com/festivals/${id}`}>
            {note && <p className="mt-2 max-w-sm text-sm text-pretty text-muted-foreground italic">{note}</p>}
          </AwardItem>
        ))}
      </AwardsListItems>
    </AwardsList>
  )
}
```

## API Reference

### AwardsList

Root wrapper. Put an `AwardsListHeader`, an optional `AwardsListHead` and the `AwardsListItems` inside.
It's a list, not a `<table>`: each award is a heading, so screen-reader users jump between awards and
hear "award, organization, project, year" in reading order, and rows can stack on phones.

Also accepts every `div` prop.

### AwardsListHeader

Top bar: put an eyebrow or title on the left and an `AwardsListSummary` on the right.

Also accepts every `div` prop.

### AwardsListSummary

Big-number totals ("12 awards · 4 SOTD") for the header or a section header.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stats` (required) | `Stat[]` | — | Headline counts, e.g. `[{ value: 12, label: "awards" }, { value: 4, label: "SOTD" }]` → "12 awards · 4 SOTD". |

Also accepts every `p` prop.

### AwardsListHead

Column labels above the rows. Hidden on mobile (rows stack) and decorative for assistive tech.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `labels` | `[React.ReactNode, React.ReactNode, React.ReactNode, React.ReactNode]` | `["Award", "Organization", "Project", "Year"]` | Column labels, in order: award, organization, project, year. |

Also accepts every `div` prop.

### AwardsListItems

The `<ul>` of `AwardItem` rows, ruled top and between rows.

Also accepts every `ul` prop.

### AwardItem

One award. On mobile the organization and project wrap under the name. Extra `children` render under the name.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `award` (required) | `React.ReactNode` | — | Award name, e.g. "Site of the Day". |
| `organization` | `React.ReactNode` | — | Awarding body, e.g. "Awwwards". |
| `project` | `React.ReactNode` | — | Project that won. |
| `year` | `number \| string` | — | Year received; a four-digit year renders as a `<time>`. |
| `count` | `number` | — | Times received; rendered as "×3" when greater than 1. |
| `countLabel` | `(count: number) => string` | `(n) => `(${n} times)`` | What screen readers hear after the award name instead of the "×3" badge, e.g. "(3 times)". Translate it here. |
| `href` | `string` | — | Link to the award page or case study; the whole row becomes clickable. Absolute URLs open in a new tab. |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the award name. Use `h4` when the list sits under an `h3`. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to links that open in a new tab. Translate it here. |

Also accepts every `li` prop.

### type Stat

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `React.ReactNode` | — | The number, e.g. `12`. |
| `label` (required) | `React.ReactNode` | — | What it counts, e.g. `"awards"`. |

## Used in templates

- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Back To Top

> Floating button that appears after scrolling, shows page progress around its edge and scrolls back to the top.

Category: Navigation · Registry item: `@portfolio-kit/back-to-top` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/back-to-top) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/back-to-top.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/back-to-top
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/back-to-top.tsx` and the kit items it uses: `use-composed-refs`, `use-reduced-motion`, `use-scroll`, `use-scroll-progress`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import { BackToTop, backToTopVariants } from "@/components/portfolio/back-to-top"
```

## Examples

### Demo

Pinned to the corner of a long page. It appears after 240px of scrolling, and its ring shows how far the reader has come.

```tsx
import { BackToTop } from "@/components/portfolio/back-to-top"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { typography } from "@/lib/typography"

const projects = [
  {
    slug: "lumen",
    title: "Lumen",
    meta: "2025 · Halcyon Labs",
    summary: "A design system and component platform powering eleven products and 140 engineers.",
    art: "interface",
  },
  {
    slug: "tidewater",
    title: "Tidewater",
    meta: "2025 · Tidewater Energy",
    summary: "Real-time grid monitoring for coastal wind farms — dense data, calm interface.",
    art: "interface",
  },
  {
    slug: "fieldnote",
    title: "Fieldnote",
    meta: "2024 · Fieldnote Inc.",
    summary: "Identity and marketing site for a note-taking app built for researchers.",
    art: "bauhaus",
  },
  {
    slug: "orbit",
    title: "Orbit",
    meta: "2024 · Open source",
    summary: "A tiny, accessible command palette for React, used by 2,000+ projects.",
    art: "interface",
  },
] as const

export default function BackToTopDemo() {
  return (
    <>
      <main className="mx-auto flex max-w-2xl flex-col gap-14 px-5 py-16 sm:px-6 md:py-20">
        <header className="flex flex-col gap-4">
          <p className={typography.eyebrow}>Selected work</p>
          <h1 className={typography.title}>Four projects, one long scroll.</h1>
          <p className={typography.lead}>Scroll down — the button slides in after 240px and fills its ring as you go.</p>
        </header>
        <ul role="list" className="flex flex-col gap-14">
          {projects.map((project) => (
            <li key={project.slug} className="flex flex-col gap-3">
              <div className="aspect-[16/10] overflow-hidden rounded-2xl border bg-muted">
                <GenerativeArt seed={project.slug} variant={project.art} />
              </div>
              <p className={`${typography.meta} mt-2`}>{project.meta}</p>
              <h2 className={typography.heading}>{project.title}</h2>
              <p className={typography.body}>{project.summary}</p>
            </li>
          ))}
        </ul>
      </main>
      <BackToTop threshold={240} />
    </>
  )
}
```

### In a Footer

`position="static"` places the button in your own layout, here at the end of a footer.

```tsx
import { BackToTop } from "@/components/portfolio/back-to-top"
import { typography } from "@/lib/typography"

const links = [
  { label: "Work", href: "#work" },
  { label: "About", href: "#about" },
  { label: "Contact", href: "#contact" },
]

export default function BackToTopInFooter() {
  return (
    <footer className="mx-auto flex w-full max-w-5xl items-center justify-between gap-6 border-t pt-6">
      <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:gap-8">
        <p className={typography.meta}>© 2025 Noa Vale</p>
        <nav aria-label="Footer">
          <ul role="list" className="flex gap-5">
            {links.map((link) => (
              <li key={link.href}>
                <a
                  href={link.href}
                  className="inline-flex min-h-6 items-center rounded-sm text-sm text-muted-foreground outline-none transition-colors hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50"
                >
                  {link.label}
                </a>
              </li>
            ))}
          </ul>
        </nav>
      </div>
      <BackToTop position="static" threshold={0} ring={false} />
    </footer>
  )
}
```

## API Reference

### BackToTop

Scrolls the window back to the top: smoothly, or instantly with reduced motion (even when the page
sets `scroll-behavior: smooth`), then moves keyboard focus to `focusTarget`. It fades in once the
page has scrolled past `threshold` and is hidden (not focusable) before that; it never takes focus
by appearing. The ring is decorative. Hidden in print. Call `event.preventDefault()` in `onClick` to
handle the scroll and focus yourself (e.g. with Lenis). Replace the arrow by passing children.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `"bottom-right" \| "bottom-left" \| "static" \| null` | `"bottom-right"` | Pin to a bottom corner of the viewport, or `static` to place it in your own layout (a footer, an article end). |
| `threshold` | `number` | `400` | Scroll distance (px) after which the button appears. `0` shows it immediately. |
| `progress` | `number` | — | Override the ring's progress (0–1) instead of tracking the page. |
| `ring` | `boolean` | `true` | Show the ring that traces reading progress around the edge. |
| `label` | `string` | `"Back to top"` | Accessible name (also the tooltip). |
| `focusTarget` | `string \| null` | `"main"` | Where focus goes when the button had it: a CSS selector for the top of your content (a skip-link target or `main`). The element is focused without scrolling, made focusable for that moment if it isn't, so the next Tab continues from the top instead of from a button that just hid itself. When nothing matches, focus stays on the button. `null` never moves focus. |

Also accepts every `button` prop.



---

# Background Pattern

> Grid, dot, line, cross or diagonal background in pure CSS, colored from theme tokens, with edge fades and an optional highlight glow.

Category: Effects · Registry item: `@portfolio-kit/background-pattern` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/background-pattern) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/background-pattern.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/background-pattern
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/background-pattern.tsx`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { BackgroundPattern, backgroundPatternVariants } from "@/components/portfolio/background-pattern"
```

## Examples

### Demo

A faint grid behind a centered hero, fading out toward the bottom with a highlight glow at the top.

```tsx
import { cn } from "@/lib/utils"
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { BackgroundPattern } from "@/components/portfolio/background-pattern"
import { typography } from "@/lib/typography"

export default function BackgroundPatternDemo() {
  return (
    <section className="relative isolate flex min-h-[34rem] flex-col items-center justify-center gap-6 px-5 py-24 text-center">
      <BackgroundPattern variant="grid" fade="top" highlight="50% 0%" />
      <AvailabilityBadge />
      <h1 className={cn(typography.display, "max-w-4xl")}>Calm, fast interfaces.</h1>
      <p className={cn(typography.lead, "max-w-xl")}>
        Design engineer helping product teams ship interfaces that feel considered, from first sketch to production.
      </p>
      <ArrowLink href="#work">Selected work</ArrowLink>
    </section>
  )
}
```

### Variants

Grid, dots, lines, cross and diagonal. Sparse patterns get stronger ink so every variant reads at the same weight.

```tsx
import { BackgroundPattern } from "@/components/portfolio/background-pattern"
import { typography } from "@/lib/typography"

const variants = ["grid", "dots", "lines", "cross", "diagonal"] as const

export default function BackgroundPatternVariants() {
  return (
    <ul role="list" className="mx-auto grid max-w-5xl gap-4 sm:grid-cols-2 lg:grid-cols-3">
      {variants.map((variant) => (
        <li
          key={variant}
          className="relative isolate flex aspect-[4/3] items-end overflow-hidden rounded-2xl border bg-card p-5 shadow-card"
        >
          <BackgroundPattern variant={variant} />
          <span className={typography.eyebrow}>{variant}</span>
        </li>
      ))}
      <li className="relative isolate flex aspect-[4/3] items-end overflow-hidden rounded-2xl border bg-card p-5 shadow-card">
        <BackgroundPattern variant="dots" tone="highlight" highlight="85% 15%" highlightSize="18rem" />
        <span className={typography.eyebrow}>dots · highlight</span>
      </li>
    </ul>
  )
}
```

### Highlight spot

Move the glow off-center with a CSS position to pull the eye toward a section title; the pattern takes on the accent around it.

```tsx
import { BackgroundPattern } from "@/components/portfolio/background-pattern"
import {
  Section,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

export default function BackgroundPatternHighlightSpot() {
  return (
    <Section className="isolate overflow-hidden">
      <BackgroundPattern variant="cross" size={48} fade="radial" highlight="25% 45%" highlightSize="30rem" />
      <SectionHeader>
        <SectionEyebrow index={1}>Approach</SectionEyebrow>
        <SectionTitle>Structure you can feel, not see.</SectionTitle>
        {/* Muted gray loses contrast over the glow: tint the foreground instead. */}
        <SectionDescription className="text-foreground/80">
          Every project starts with a grid, a type scale and a handful of tokens — the quiet decisions that make
          everything after them faster.
        </SectionDescription>
      </SectionHeader>
    </Section>
  )
}
```

### In a card

Texture a single card, like a newsletter tile, with dots that fade out before the copy.

```tsx
import { Newspaper } from "lucide-react"

import { cn } from "@/lib/utils"
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { BackgroundPattern } from "@/components/portfolio/background-pattern"
import { typography } from "@/lib/typography"

export default function BackgroundPatternInACard() {
  return (
    <article className="relative isolate flex w-full max-w-md flex-col gap-10 overflow-hidden rounded-2xl border bg-card p-6 shadow-card md:p-8">
      <BackgroundPattern variant="dots" fade="top" highlight="85% 0%" highlightSize="18rem" className="bottom-1/3" />
      <div className="flex items-start justify-between gap-4">
        <span className="inline-flex size-10 items-center justify-center rounded-xl border bg-background">
          <Newspaper aria-hidden className="size-[1.1rem]" />
        </span>
        {/* This sits on the glow: muted gray loses contrast there, so tint the foreground instead. */}
        <span className={cn(typography.meta, "text-foreground/80")}>Monthly · 2,400 readers</span>
      </div>
      <div className="flex flex-col gap-3">
        <h2 className={typography.heading}>Notes on design engineering</h2>
        <p className={typography.body}>
          One short essay a month on motion, design systems and the craft between Figma and production.
        </p>
        <ArrowLink href="#subscribe" className="mt-2 w-fit">
          Subscribe
        </ArrowLink>
      </div>
    </article>
  )
}
```

## API Reference

### BackgroundPattern

Put it inside a `relative isolate` parent: it sits at `-z-10` behind the
parent's content and never catches pointer events. The lines stay faint, but
the `highlight` glow tints the surface: small `text-muted-foreground` copy on
the glow can drop under 4.5:1, so give it `text-foreground/80`. Forced-colors
mode removes the pattern (it is decoration only); print keeps it as drawn.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"grid" \| "dots" \| "lines" \| "cross" \| "diagonal"` | `"grid"` | The motif: square `grid`, `dots`, horizontal `lines` (ruled paper), `cross` (plus marks) or 45° `diagonal` hatching. |
| `size` | `number` | — | Tile size (grid cell, dot spacing, line gap) in px. Defaults per variant: grid/cross 40, lines 32, dots 20, diagonal 14. |
| `stroke` | `number` | `1` | Line width / dot radius in px. |
| `tone` | `"foreground" \| "border" \| "highlight"` | `"foreground"` | Pattern color: `foreground` (a faint ink that works on any surface), `border` (matches your hairlines) or `highlight` (the accent). |
| `highlight` | `boolean \| string` | `false` | Soft highlight glow that also tints the pattern near it. `true` places it at the top center; pass a CSS position (e.g. `"20% 30%"`) to move it. |
| `highlightSize` | `string` | `"36rem"` | Glow radius (any CSS length). |
| `fade` | `"radial" \| "top" \| "bottom" \| "none"` | `"radial"` | Mask the edges so the pattern dissolves into the page: `radial` (vignette), `top`/`bottom` (keep that edge), or `none`. |

Also accepts every `div` prop.



---

# Before After

> Comparison slider for redesigns. Drag, click or use the keyboard to wipe between two layers, horizontally or vertically.

Category: Work · Registry item: `@portfolio-kit/before-after` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/before-after) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/before-after.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/before-after
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/before-after.tsx` and the kit items it uses: `use-composed-refs`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  BeforeAfter,
  BeforeAfterLayer,
} from "@/components/portfolio/before-after"

<BeforeAfter ratio="video" label="Compare the old dashboard with the redesign">
  <BeforeAfterLayer side="before">
    <img src="/work/dashboard-before.jpg" alt="Legacy dashboard" />
  </BeforeAfterLayer>
  <BeforeAfterLayer side="after">
    <img src="/work/dashboard-after.jpg" alt="Redesigned dashboard" />
  </BeforeAfterLayer>
</BeforeAfter>
```

## Examples

### Demo

Compare an old and a new design in one frame. Drag, click or use the arrow keys to move the divider.

```tsx
import { BeforeAfter, BeforeAfterLayer } from "@/components/portfolio/before-after"
import { GenerativeArt } from "@/components/portfolio/generative-art"

export default function BeforeAfterDemo() {
  return (
    <BeforeAfter
      ratio="video"
      label="Compare the legacy dashboard with the redesign"
      figureClassName="mx-auto max-w-3xl"
      caption={
        <>
          <span className="shrink-0 text-highlight-ink">Fig. 3</span>
          <span>The legacy Tidewater dashboard against the redesign. Drag the handle to compare.</span>
        </>
      }
    >
      <BeforeAfterLayer side="after">
        <GenerativeArt seed="tidewater-console" variant="interface" hue={195} label="Redesigned dashboard, vivid palette" />
      </BeforeAfterLayer>
      <BeforeAfterLayer side="before">
        <GenerativeArt
          seed="tidewater-2019"
          variant="interface"
          className="contrast-75 grayscale"
          label="Legacy dashboard, muted palette"
        />
      </BeforeAfterLayer>
    </BeforeAfter>
  )
}
```

### Vertical

Wipe top to bottom with custom chip labels, for tall screens or two versions of an identity.

```tsx
import { BeforeAfter, BeforeAfterLayer } from "@/components/portfolio/before-after"
import { GenerativeArt } from "@/components/portfolio/generative-art"

export default function BeforeAfterVertical() {
  return (
    <BeforeAfter
      orientation="vertical"
      ratio="portrait"
      defaultPosition={40}
      label="Compare the 2019 and 2025 identity"
      className="mx-auto max-w-xs"
    >
      <BeforeAfterLayer side="after" label="2025">
        <GenerativeArt seed="atlas-identity" variant="bauhaus" label="2025 identity, full colour" />
      </BeforeAfterLayer>
      <BeforeAfterLayer side="before" label="2019">
        <GenerativeArt seed="atlas-identity" variant="bauhaus" className="grayscale" label="2019 identity, monochrome" />
      </BeforeAfterLayer>
    </BeforeAfter>
  )
}
```

### Wireframe to Final

Layers can hold any markup, not just images. Here a wireframe wipes into the finished screen.

```tsx
import { BeforeAfter, BeforeAfterLayer } from "@/components/portfolio/before-after"
import { GenerativeArt } from "@/components/portfolio/generative-art"

const tiles = ["interface", "landscape", "portrait"] as const

export default function BeforeAfterWireframe() {
  return (
    <BeforeAfter
      ratio="auto"
      defaultPosition={45}
      label="Compare the wireframe with the final design"
      className="mx-auto aspect-square max-w-xl border shadow-card sm:aspect-[4/3]"
    >
      <BeforeAfterLayer side="after" label="Final">
        <div className="flex size-full flex-col gap-4 bg-card px-5 pt-14 pb-5 md:gap-5 md:px-8 md:pt-16 md:pb-8">
          <div className="flex items-center justify-between">
            <span className="font-heading text-lg">Fieldnote</span>
            <span className="h-7 rounded-pill bg-primary px-3 text-xs leading-7 font-medium text-primary-foreground">
              Try it free
            </span>
          </div>
          <p className="max-w-[16ch] font-heading text-2xl leading-tight text-balance md:text-4xl">
            Notes that think like a researcher.
          </p>
          <div className="mt-auto grid min-h-16 flex-1 grid-cols-3 gap-3">
            {tiles.map((variant) => (
              <GenerativeArt key={variant} seed={`fieldnote-${variant}`} variant={variant} className="rounded-lg" />
            ))}
          </div>
        </div>
      </BeforeAfterLayer>
      <BeforeAfterLayer side="before" label="Wireframe">
        <div aria-hidden className="flex size-full flex-col gap-4 bg-muted px-5 pt-14 pb-5 md:gap-5 md:px-8 md:pt-16 md:pb-8">
          <div className="flex items-center justify-between">
            <span className="h-4 w-24 rounded-sm bg-foreground/15" />
            <span className="h-7 w-24 rounded-pill border border-dashed border-foreground/30" />
          </div>
          {/* Same type size as the real headline, so each bar sits on one of its lines. */}
          <div className="flex max-w-[16ch] flex-col font-heading text-2xl leading-tight md:text-4xl">
            <span className="flex h-[1lh] items-center">
              <span className="h-3/4 w-full rounded-sm bg-foreground/15" />
            </span>
            <span className="flex h-[1lh] items-center">
              <span className="h-3/4 w-2/3 rounded-sm bg-foreground/15" />
            </span>
          </div>
          <div className="mt-auto grid min-h-16 flex-1 grid-cols-3 gap-3">
            {tiles.map((variant) => (
              <span key={variant} className="rounded-lg border border-dashed border-foreground/30" />
            ))}
          </div>
        </div>
      </BeforeAfterLayer>
    </BeforeAfter>
  )
}
```

## API Reference

### BeforeAfter

The comparison frame. Put two `BeforeAfterLayer`s inside. The handle is a `role="slider"`
(value = % of "before" shown), so it works with the keyboard and screen readers. Click or drag
anywhere on the frame to move the divider; dragging never re-renders React. On touch screens a
horizontal swipe drags and a vertical one scrolls the page; a vertical slider drags from its handle.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | `"photo" \| "video" \| "square" \| "portrait" \| "wide" \| "auto"` | `"photo"` | Frame shape: `photo` 4:3, `video` 16:9, `square`, `portrait` 4:5 or `wide` 21:9. Both layers fill the same frame and `<img>`s are cropped to it (`object-cover`), so the two pictures line up. `auto` sets no ratio: give the frame a height or an `aspect-*` class yourself. |
| `radius` | `"default" \| "lg" \| "none"` | `"lg"` | Corner radius: `default` follows the theme, `lg` is larger, `none` is square. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Wipe direction: `horizontal` (before on the left) or `vertical` (before on top). |
| `defaultPosition` | `number` | `50` | Initial handle position, 0–100: how much of the "before" layer shows, from the left (or top). |
| `step` | `number` | `2` | Keyboard step in %. ←/→ (or ↑/↓ when vertical) move by one step, Page Up/Page Down by ten, Home/End to the ends. |
| `label` | `string` | `"Before and after comparison"` | Accessible name of the slider, e.g. "Compare the old dashboard with the redesign". |
| `onPositionChange` | `(position: number) => void` | — | Called (at most once per frame) while the position changes. |
| `caption` | `React.ReactNode` | — | Wraps the slider in a `<figure>` with this `<figcaption>` underneath, in the kit's mono caption style. |
| `figureClassName` | `string` | — | Class for the `<figure>` wrapper (only rendered with a `caption`). |
| `captionClassName` | `string` | — | Class for the `<figcaption>`. |

Also accepts every `div` prop.

### BeforeAfterLayer

One side of the comparison. The "before" layer sits on top and is clipped
to the handle position; the "after" layer fills the frame underneath. A direct `<img>` child fills
the frame (`object-cover`); give both images the same framing and their own `alt`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` (required) | `"before" \| "after"` | — | Which side of the comparison this layer is. "before" always stacks on top, so order doesn't matter. |
| `label` | `React.ReactNode \| false` | — | Chip text. Defaults to "Before"/"After"; pass `false` to hide it. |

Also accepts every `div` prop.

## Used in templates

- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)



---

# Bento Grid

> Six-column grid of spanning cards with labels, titles and full-bleed visuals, for about sections, stats and tool stacks.

Category: Layout · Registry item: `@portfolio-kit/bento-grid` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/bento-grid) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/bento-grid.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/bento-grid
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/bento-grid.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  BentoCard,
  BentoCardDescription,
  BentoCardHeader,
  BentoCardLabel,
  BentoCardTitle,
  BentoCardVisual,
  BentoGrid,
} from "@/components/portfolio/bento-grid"

<BentoGrid>
  <BentoCard colSpan={2} rowSpan={2}>
    <BentoCardVisual cover>
      <img src="/me.jpg" alt="" />
    </BentoCardVisual>
  </BentoCard>
  <BentoCard colSpan={4}>
    <BentoCardHeader>
      <BentoCardLabel>About</BentoCardLabel>
      <BentoCardTitle>Design engineer crafting calm, fast interfaces.</BentoCardTitle>
      <BentoCardDescription>Nine years across product design and front-end.</BentoCardDescription>
    </BentoCardHeader>
  </BentoCard>
</BentoGrid>
```

## Examples

### Demo

An about section: portrait, intro, location, tools and a few numbers, with cards spanning columns and rows.

```tsx
import { Layers, MapPin, UserRound } from "lucide-react"

import { StatusDot } from "@/components/portfolio/availability-badge"
import {
  BentoCard,
  BentoCardContent,
  BentoCardDescription,
  BentoCardHeader,
  BentoCardLabel,
  BentoCardTitle,
  BentoCardVisual,
  BentoGrid,
} from "@/components/portfolio/bento-grid"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { LocalTime } from "@/components/portfolio/local-time"
import { typography } from "@/lib/typography"

const stack = ["TypeScript", "React", "Next.js", "Tailwind", "Figma", "Rive", "Postgres"]

const stats = [
  { value: "9", unit: "yrs", label: "Shipping interfaces" },
  { value: "40+", label: "Products launched" },
  { value: "4k", unit: "★", label: "Open-source stars" },
]

export default function BentoGridDemo() {
  return (
    <BentoGrid className="mx-auto max-w-5xl">
      <BentoCard colSpan={2} rowSpan={2} className="text-white">
        <BentoCardVisual
          cover
          className="after:absolute after:inset-0 after:bg-gradient-to-t after:from-black/70 after:via-black/10 after:to-transparent"
        >
          <GenerativeArt seed="noa-portrait" variant="portrait" label="Portrait of Noa Vale" />
        </BentoCardVisual>
        <BentoCardHeader className="mt-auto">
          <BentoCardLabel className="text-white/75">Hello</BentoCardLabel>
          <BentoCardTitle className="text-2xl md:text-3xl">I&apos;m Noa.</BentoCardTitle>
        </BentoCardHeader>
      </BentoCard>

      <BentoCard colSpan={4}>
        <BentoCardHeader className="h-full justify-center gap-3 md:p-8">
          <BentoCardLabel>
            <UserRound aria-hidden /> About
          </BentoCardLabel>
          <BentoCardTitle as="h2" className="max-w-xl text-2xl text-balance md:text-3xl">
            Design engineer crafting calm, fast interfaces for ambitious teams.
          </BentoCardTitle>
          <BentoCardDescription className="max-w-lg">
            Nine years at the seam of product design and front-end engineering — design systems, motion and the details
            in between.
          </BentoCardDescription>
        </BentoCardHeader>
      </BentoCard>

      <BentoCard colSpan={2}>
        <BentoCardVisual
          aria-hidden
          className="absolute inset-0 -z-10 bg-[radial-gradient(color-mix(in_oklab,var(--foreground)_18%,transparent)_1px,transparent_1px)] [mask-image:radial-gradient(ellipse_at_70%_40%,black_20%,transparent_75%)] bg-[size:14px_14px]"
        >
          <span className="absolute top-[40%] left-[70%] -translate-1/2">
            <span className="block size-3 rounded-full bg-highlight ring-4 ring-highlight/25" />
          </span>
        </BentoCardVisual>
        <BentoCardHeader className="mt-auto">
          <BentoCardLabel>
            <MapPin aria-hidden /> Based in
          </BentoCardLabel>
          <BentoCardTitle>Lisbon, Portugal</BentoCardTitle>
          <LocalTime timeZone="Europe/Lisbon" city={false} icon={false} blink={false} className={typography.meta} />
        </BentoCardHeader>
      </BentoCard>

      <BentoCard colSpan={2}>
        <BentoCardHeader>
          <BentoCardLabel>
            <Layers aria-hidden /> Stack
          </BentoCardLabel>
          <BentoCardTitle>Tools I reach for</BentoCardTitle>
        </BentoCardHeader>
        <BentoCardContent className="justify-end">
          <ul role="list" aria-label="Tools" className="flex flex-wrap gap-1.5">
            {stack.map((tool) => (
              <li key={tool} className="rounded-pill border bg-background px-3 py-1 text-xs font-medium text-muted-foreground">
                {tool}
              </li>
            ))}
          </ul>
        </BentoCardContent>
      </BentoCard>

      <BentoCard colSpan={4}>
        <BentoCardContent className="justify-center">
          <dl className="grid grid-cols-3 divide-x">
            {stats.map((stat) => (
              <div key={stat.label} className="flex flex-col-reverse justify-end gap-2 px-3 first:pl-0 last:pr-0 md:px-6">
                <dt className={typography.meta}>{stat.label}</dt>
                <dd className="font-heading text-4xl leading-none tabular-nums md:text-5xl">
                  {stat.value}
                  {stat.unit && <span className="ml-1 text-lg text-muted-foreground md:text-xl">{stat.unit}</span>}
                </dd>
              </div>
            ))}
          </dl>
        </BentoCardContent>
      </BentoCard>

      <BentoCard colSpan={2} href="#contact">
        <BentoCardHeader className="h-full justify-between gap-6">
          <BentoCardLabel>
            <StatusDot status="available" /> Availability
          </BentoCardLabel>
          <div className="flex flex-col gap-1.5">
            <BentoCardTitle>Taking projects from November</BentoCardTitle>
            <BentoCardDescription>Design systems, product design and front-end builds.</BentoCardDescription>
          </div>
        </BentoCardHeader>
      </BentoCard>
    </BentoGrid>
  )
}
```

### Linked Projects

Give a card an `href` and its title becomes a whole-card link. Mix wide and narrow spans for a project index.

```tsx
import {
  BentoCard,
  BentoCardDescription,
  BentoCardHeader,
  BentoCardTitle,
  BentoCardVisual,
  BentoGrid,
} from "@/components/portfolio/bento-grid"
import { GenerativeArt } from "@/components/portfolio/generative-art"

const projects = [
  { slug: "lumen", title: "Lumen", meta: "Design system · 2025", art: "interface", span: 4 },
  { slug: "tidewater", title: "Tidewater", meta: "Data viz · 2025", art: "interface", span: 2 },
  { slug: "fieldnote", title: "Fieldnote", meta: "Brand & web · 2024", art: "bauhaus", span: 2 },
  { slug: "orbit", title: "Orbit Analytics", meta: "Front-end · 2024", art: "interface", span: 4 },
] as const

export default function BentoGridProjects() {
  return (
    <BentoGrid className="mx-auto max-w-5xl auto-rows-[18rem] md:auto-rows-[20rem]">
      {projects.map((project) => (
        <BentoCard key={project.slug} colSpan={project.span} href={`#${project.slug}`}>
          <BentoCardVisual>
            <GenerativeArt seed={project.slug} variant={project.art} />
          </BentoCardVisual>
          <BentoCardHeader className="border-t">
            <BentoCardTitle>{project.title}</BentoCardTitle>
            <BentoCardDescription>{project.meta}</BentoCardDescription>
          </BentoCardHeader>
        </BentoCard>
      ))}
    </BentoGrid>
  )
}
```

### Studio Services

A studio’s services as a bento: two halves for the main offers, three thirds for the rest and a full-width card that links to the brief.

```tsx
import { Blocks, Film, Presentation } from "lucide-react"

import {
  BentoCard,
  BentoCardContent,
  BentoCardDescription,
  BentoCardHeader,
  BentoCardLabel,
  BentoCardTitle,
  BentoCardVisual,
  BentoGrid,
} from "@/components/portfolio/bento-grid"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { typography } from "@/lib/typography"

const main = [
  {
    title: "Brand identity",
    description: "Naming, logo, type and a system your team can actually use.",
    seed: "studio-brand",
    art: "bauhaus",
  },
  {
    title: "Websites & products",
    description: "Marketing sites and product UI, designed and built in the same room.",
    seed: "studio-web",
    art: "interface",
  },
] as const

const more = [
  { title: "Motion", description: "Logo animations, launch films and UI micro-interactions.", icon: Film },
  { title: "Design systems", description: "Tokens, components and docs that outlive the project.", icon: Blocks },
  { title: "Workshops", description: "Two-day sprints to align a team before a redesign.", icon: Presentation },
]

export default function BentoGridServices() {
  return (
    <BentoGrid className="mx-auto max-w-5xl">
      {main.map((service, i) => (
        <BentoCard key={service.seed} colSpan={3}>
          {/* A fixed ratio keeps both images the same height, however long each description runs. */}
          <BentoCardVisual className="aspect-[16/9] flex-none">
            <GenerativeArt seed={service.seed} variant={service.art} />
          </BentoCardVisual>
          <BentoCardHeader className="flex-1 border-t">
            <BentoCardLabel>{String(i + 1).padStart(2, "0")}</BentoCardLabel>
            <BentoCardTitle>{service.title}</BentoCardTitle>
            <BentoCardDescription>{service.description}</BentoCardDescription>
          </BentoCardHeader>
        </BentoCard>
      ))}

      {more.map(({ title, description, icon: Icon }, i) => (
        // On the two-column tablet grid, the odd one out spans the row instead of leaving a hole.
        <BentoCard key={title} colSpan={2} className={i === more.length - 1 ? "sm:col-span-2 md:col-span-2" : undefined}>
          <BentoCardHeader className="h-full justify-between gap-6">
            <BentoCardLabel>
              <Icon aria-hidden /> {String(i + 3).padStart(2, "0")}
            </BentoCardLabel>
            <div className="flex flex-col gap-1.5">
              <BentoCardTitle>{title}</BentoCardTitle>
              <BentoCardDescription>{description}</BentoCardDescription>
            </div>
          </BentoCardHeader>
        </BentoCard>
      ))}

      <BentoCard colSpan={6} href="#brief" className="bg-muted/50">
        <BentoCardContent className="justify-center gap-4 md:flex-row md:items-center md:justify-between md:gap-8 md:p-8">
          <div className="flex flex-col gap-1.5">
            <BentoCardLabel>Next opening · March</BentoCardLabel>
            <BentoCardTitle as="h2" className="text-2xl md:text-3xl">
              Have a project in mind? Send us the brief.
            </BentoCardTitle>
          </div>
          <p className={`${typography.meta} md:text-right`}>
            Projects from €12k
            <br />
            6–10 weeks
          </p>
        </BentoCardContent>
      </BentoCard>
    </BentoGrid>
  )
}
```

## API Reference

### BentoGrid

The grid: one column on mobile, two on tablets, six from `md` up. Rows grow with their
content (min ~11rem) and `grid-flow-dense` backfills gaps left by wide cards. Override
the rows with `auto-rows-*` for uniform tiles.

Also accepts every `div` prop.

### BentoCard

A tile in the grid. Compose a `BentoCardVisual`, `BentoCardHeader` and/or `BentoCardContent` inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colSpan` | `2 \| 3 \| 4 \| 6 \| null` | `2` | Columns spanned on the six-column desktop grid (`2` = a third, `3` = half, `4` = two thirds, `6` = full width). `4` and `6` also span both columns of the two-column tablet grid. |
| `rowSpan` | `1 \| 2 \| null` | `1` | `2` makes a tall card spanning two rows from `sm` up (and gives it extra height on mobile). |
| `href` | `string` | — | Makes the whole card a link (via `BentoCardTitle`). External URLs open in a new tab. The link covers the card, so don't put other links or buttons inside a linked card. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to the title link when `href` opens in a new tab. Translate it here. |

Also accepts every `article` prop.

### BentoCardHeader

Padded stack for the label, title and description. Add `mt-auto` to push it to the bottom of a tall card.

Also accepts every `div` prop.

### BentoCardLabel

Mono label with an optional leading icon, e.g. "Based in", "Now playing"…

Also accepts every `p` prop.

### BentoCardTitle

The card heading (`h3` by default; set `as` to keep the page outline). When the card has an `href`, it renders the link that makes the whole card clickable, plus an arrow.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level. |

Also accepts every `h3` prop.

### BentoCardDescription

Supporting copy under the title.

Also accepts every `p` prop.

### BentoCardContent

Padded free-form content (stats, chips, players…). Grows to fill the card.

Also accepts every `div` prop.

### BentoCardVisual

Media slot that bleeds to the card edges (the card's rounded corners clip it). Zooms gently while a linked card is hovered.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cover` | `boolean` | `false` | Fill the entire card behind the other parts (add your own scrim for legibility). |

Also accepts every `div` prop.



---

# Bio

> About-me block with a captioned portrait, prose that opens with a lead paragraph, a facts list and an optional sign-off.

Category: About · Registry item: `@portfolio-kit/bio` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/bio) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/bio.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/bio
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/bio.tsx` and the kit items it uses: `media`, `typography`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  Bio,
  BioContent,
  BioFact,
  BioFacts,
  BioPortrait,
  BioSignoff,
} from "@/components/portfolio/bio"

<Bio>
  <BioPortrait src="/portrait.jpg" alt="Portrait of Noa" caption="The studio, Lisbon" />
  <BioContent>
    <p>I'm Noa, a design engineer working between product design and front-end code.</p>
    <p>I lead the design system at Halcyon Labs.</p>
    <BioFacts>
      <BioFact label="Based in">Lisbon, PT</BioFact>
      <BioFact label="Focus">Design systems</BioFact>
    </BioFacts>
    <BioSignoff>— Noa</BioSignoff>
  </BioContent>
</Bio>
```

## Examples

### Demo

The classic about-me layout: a captioned portrait beside a lead paragraph, a few facts and a hand-signed sign-off.

```tsx
import { Bio, BioContent, BioFact, BioFacts, BioPortrait, BioSignoff } from "@/components/portfolio/bio"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Section } from "@/components/portfolio/section"

export default function BioDemo() {
  return (
    <Section spacing="sm">
      <Bio>
        <BioPortrait caption="Fig. 1 — The studio, Lisbon 2025" bordered>
          <GenerativeArt seed="noa-portrait" variant="portrait" label="Portrait of Noa" />
        </BioPortrait>
        <BioContent>
          <p>I&rsquo;m Noa, a design engineer working at the seam between product design and front-end code.</p>
          <p>
            For nine years I&rsquo;ve helped startups and studios turn rough ideas into interfaces that feel inevitable.
            Today I lead the design system at <a href="#halcyon">Halcyon Labs</a>, where a small team and I keep eleven
            products speaking the same visual language.
          </p>
          <p>
            I care about <strong>typography, motion and accessibility</strong> — in roughly that order of obsession.
            Outside of work I shoot film, run along the river and tinker with <a href="#sketches">generative art</a>.
          </p>
          <BioFacts>
            <BioFact label="Based in">Lisbon, PT</BioFact>
            <BioFact label="Focus">Design systems</BioFact>
            <BioFact label="Experience">9 years</BioFact>
            <BioFact label="Currently">Staff DE, Halcyon</BioFact>
          </BioFacts>
          <BioSignoff>— Noa</BioSignoff>
        </BioContent>
      </Bio>
    </Section>
  )
}
```

### Stacked

A wide image above the prose, for single-column about pages and long-form personal sites.

```tsx
import { Bio, BioContent, BioFact, BioFacts, BioPortrait } from "@/components/portfolio/bio"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Section } from "@/components/portfolio/section"

export default function BioStacked() {
  return (
    <Section spacing="sm" size="sm">
      <Bio variant="stacked">
        <BioPortrait caption="The view from the studio window, Lisbon" bordered>
          <GenerativeArt seed="studio-window" variant="landscape" label="Hills and sky seen from the studio window" />
        </BioPortrait>
        <BioContent>
          <p>Small studio, big opinions about whitespace. I design and build calm interfaces for ambitious teams.</p>
          <p>
            Most of my work lives where design systems meet product: token pipelines, component APIs and the motion that
            ties them together. I take on two or three projects a year, always with a clear scope and a team that cares
            about the details.
          </p>
          <BioFacts>
            <BioFact label="Based in">Lisbon, PT</BioFact>
            <BioFact label="Available">Q1 2026</BioFact>
            <BioFact label="Clients">24 teams</BioFact>
            <BioFact label="Languages">EN, PT, ES</BioFact>
          </BioFacts>
        </BioContent>
      </Bio>
    </Section>
  )
}
```

### Prose Only

No image, only prose: a readable column with a lead paragraph and highlighted links. Suits minimal, writing-first sites.

```tsx
import { Bio, BioContent, BioSignoff } from "@/components/portfolio/bio"

export default function BioProseOnly() {
  return (
    <Bio variant="stacked" className="mx-auto w-full max-w-2xl py-8 md:py-12">
      <BioContent>
        <p>Hi, I&rsquo;m Noa. I make software feel a little more human.</p>
        <p>
          I started out setting type for a small publisher, then fell into front-end development when the publisher
          needed a website. That mix of <strong>editorial care and engineering rigour</strong> still shapes everything I
          build.
        </p>
        <p>
          These days I write about <a href="#writing">design systems</a> and <a href="#talks">interface motion</a>, and
          maintain a handful of open-source tools. If you&rsquo;d like to work together, <a href="#contact">say hello</a>.
        </p>
        <BioSignoff>Noa V.</BioSignoff>
      </BioContent>
    </Bio>
  )
}
```

## API Reference

### Bio

Layout root. Put a `BioPortrait` (optional) and a `BioContent` inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"split" \| "stacked" \| null` | `"split"` | `split` puts the portrait beside the prose from `md` up (it stacks on mobile); `stacked` is a single readable column with a wide image on top. |

Also accepts every `div` prop.

### BioPortrait

The picture. Wraps `Media`, so it takes `src`/`alt`, `caption`, `bordered`, `ratio`
and `radius`, or artwork as children. The ratio defaults to `portrait` in the split
layout and `wide` when stacked, and reserves the space before the image loads. With a
`caption` it renders a `<figure>` and `<figcaption>`. Describe the photo in `alt`
("Noa at her desk in the studio"); the caption is extra context, not a replacement.
Prefer a `Portrait` for a polaroid, arch or circle look; it works in the same slot.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | `"photo" \| "video" \| "square" \| "portrait" \| "wide" \| "tall" \| "auto"` | — | Aspect ratio of the frame: `photo` 4:3, `video` 16:9, `square`, `portrait` 4:5, `tall` 3:4, `wide` 21:9. `auto` sets no ratio: the image or video keeps its own shape (pass `width`/`height` in `imgProps` or `videoProps` to reserve the space before it loads), or size the frame yourself with `className`/`frameClassName` (`aspect-*`, `size-full`). Artwork alone has no size of its own. |
| `radius` | `"default" \| "none" \| "lg" \| "full"` | `"lg"` | Corner radius: `default` follows the theme, `lg` is larger, `full` makes a circle (use with `square`), `none` is square. |
| `bordered` | `boolean` | — | Draw a hairline border, for screenshots with white edges on a white page. |
| `src` | `string` | — | Image URL. Loads lazily and fades in from a blur once decoded (at once under reduced motion). |
| `alt` | `string` | — | Text alternative for the image or video. Describe what the media shows when it carries content; leave it empty (the default) when it's decorative or the caption or nearby text already says it. |
| `priority` | `boolean` | — | Mark the image as the page's main, above-the-fold image (the LCP element): it loads eagerly with high fetch priority and shows at once, without the blur-up fade. |
| `video` | `string` | — | Video source. Plays muted and looped while on screen and the tab is visible. Under reduced motion, reduced data or Save-Data it doesn't start; it shows `poster` and controls instead. |
| `poster` | `string` | — | Poster frame shown before the video plays (and instead of it under reduced motion or data saving). |
| `zoom` | `boolean` | — | Scale the media when the frame (or any ancestor `.group`) is hovered. Off for reduced motion. |
| `caption` | `React.ReactNode` | — | Caption under the frame. When set, Media renders a `<figure>` with a `<figcaption>`; otherwise a single `<div>`. |
| `frameClassName` | `string` | — | Classes for the frame itself. With a `caption`, `className` styles the outer `<figure>`, so use this for a per-breakpoint ratio: `ratio="auto" frameClassName="aspect-[4/5] sm:aspect-video"`. |
| `children` | `React.ReactNode` | — | Artwork (e.g. `<GenerativeArt />`) or overlays rendered inside the frame, on top of any image or video. |
| `imgProps` | `Omit<React.ComponentProps<"img">, "src" \| "alt">` | — | Extra props for the `<img>`: `sizes` and `srcSet` for responsive images, `width`/`height`… |
| `videoProps` | `Omit<React.ComponentProps<"video">, "src" \| "poster">` | — | Extra props for the `<video>` (`controls`, `preload`, tracks…). With `controls`, the visitor's play and pause win. |
| `sticky` | `boolean` | `true` | Keep the portrait in view while the prose scrolls (split layout, `md` and up). |

Other props are forwarded to the root element.

### BioContent

Prose container. Paragraphs keep a ~62ch measure and the first one reads as a
lead (heading face, larger) when it is the first child. `<strong>` lifts to the foreground
color; inline links get a quiet underline that fills with the highlight on hover. Long words
and URLs wrap instead of overflowing.

Also accepts every `div` prop.

### BioFacts

Key facts as a description list under a rule. Two columns, four once the prose
column is wide enough (it responds to its container, not the viewport).

Also accepts every `dl` prop.

### BioFact

One fact: a small label (`<dt>`) over its value (`<dd>`, the children).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `React.ReactNode` | — | The term, e.g. "Based in". Rendered as the `<dt>`. |

Also accepts every `div` prop.

### BioSignoff

A signature-style closing line, set slightly askew in the heading face. Put it last in
`BioContent`. For a hand-drawn signature that writes itself, use the `Signature`
component in the same place instead.

Also accepts every `p` prop.

## Used in templates

- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)



---

# Blogroll

> An indie-web “sites I read” list: a monogram tile, site name, author, one line on why, the domain and when it last posted, as a list or a compact grid, with an OPML/RSS row.

Category: Content · Registry item: `@portfolio-kit/blogroll` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/blogroll) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/blogroll.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/blogroll
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/blogroll.tsx` and the kit items it uses: `format`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  Blogroll,
  BlogrollFeeds,
  BlogrollItem,
} from "@/components/portfolio/blogroll"

<div>
  <Blogroll>
    <BlogrollItem href="https://example.com" name="Slow Pixels" author="Ines Moreau" updated="2025-10-02">
      Long essays on interface craft.
    </BlogrollItem>
    <BlogrollItem href="https://example.com/notes" name="Margin Notes" author="Theo Park">
      Short weekly links about type.
    </BlogrollItem>
  </Blogroll>
  <BlogrollFeeds opml="/blogroll.opml" rss="/feeds/blogroll.xml" />
</div>
```

## Examples

### Demo

The sites you read, and why, with when each last posted and an OPML file so visitors can follow them all.

```tsx
import { Blogroll, BlogrollFeeds, BlogrollItem } from "@/components/portfolio/blogroll"
import { GenerativeArt } from "@/components/portfolio/generative-art"

const sites = [
  {
    name: "Field Notes on Type",
    author: "Mira Okafor",
    href: "https://fieldnotes.example.com",
    updated: "2025-10-11",
    why: "Slow, generous essays on typefaces and the people who draw them.",
    art: "bauhaus",
  },
  {
    name: "Small Tools",
    author: "Theo Lindqvist",
    href: "https://smalltools.example.com",
    updated: "2025-10-02",
    why: "One tiny, well-made web tool a month, with the source and the thinking.",
    art: "rings",
  },
  {
    name: "Paper Garden",
    author: "Ana Duarte",
    href: "https://papergarden.example.com",
    updated: "2025-08-19",
    why: "A digital garden about craft, attention and making things by hand.",
    art: "mesh",
  },
  {
    name: "Latency",
    author: "Sam Whitlock",
    href: "https://latency.example.com",
    updated: "2025-09-27",
    why: "Performance deep-dives that always end with a number you can use.",
    art: "waves",
  },
] as const

export default function BlogrollDemo() {
  return (
    <div className="mx-auto w-full max-w-3xl">
      <Blogroll now="2025-10-14">
        {sites.map((site) => (
          <BlogrollItem
            key={site.href}
            href={site.href}
            name={site.name}
            author={site.author}
            updated={site.updated}
            icon={<GenerativeArt seed={site.name} variant={site.art} grain={false} />}
          >
            {site.why}
          </BlogrollItem>
        ))}
      </Blogroll>
      <BlogrollFeeds opml="/blogroll.opml" rss="/feeds/blogroll.xml" />
    </div>
  )
}
```

### Grid

`variant="grid"` for a compact wall of friends’ sites, with letter monograms instead of artwork.

```tsx
import { Blogroll, BlogrollItem } from "@/components/portfolio/blogroll"

const friends = [
  { name: "Juniper Lab", author: "Kai Moreno", href: "https://juniper.example.com" },
  { name: "Rest of the Week", author: "Priya Nair", href: "https://restoftheweek.example.com" },
  { name: "Northwind Notes", author: "Elin Berg", href: "https://northwind.example.com" },
  { name: "Low Orbit", author: "Dev Patel", href: "https://loworbit.example.com" },
  { name: "Hand & Machine", author: "Iris Chen", href: "https://handmachine.example.com" },
  { name: "Quiet Pixels", author: "Leo Martin", href: "https://quietpixels.example.com" },
]

export default function BlogrollGrid() {
  return (
    <Blogroll variant="grid" className="mx-auto w-full max-w-4xl">
      {friends.map((f) => (
        <BlogrollItem key={f.href} href={f.href} name={f.name} author={f.author} />
      ))}
    </Blogroll>
  )
}
```

## API Reference

### Blogroll

The list (`<ul>`). Put `<BlogrollItem>`s inside, and a `<BlogrollFeeds>` after it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"list" \| "grid"` | `"list"` | `list`: roomy rows with the "why" line. `grid`: compact cards, several per row. |
| `now` | `DateInput` | — | Reference time for "updated 3 days ago". Pass a fixed date (e.g. the build time) for deterministic output: without it, the server and the browser each use their own clock. |
| `locale` | `string` | `"en-US"` | Locale for "3 days ago" and the full date on hover. |

Also accepts every `ul` prop.

### BlogrollItem

One site: tile, name and author, the "why" line, then domain and last update.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` (required) | `string` | — | The site's URL. The whole row or card links here (opens in a new tab, marked with ↗). |
| `name` (required) | `string` | — | Site name. |
| `author` | `React.ReactNode` | — | Who writes it. |
| `domain` | `string` | — | Shown in mono. Defaults to the host of `href`. |
| `updated` | `DateInput` | — | When it last published: shown as "3 days ago", with the full date on hover. |
| `icon` | `React.ReactNode` | — | Tile artwork, e.g. `<GenerativeArt seed="…" />` or an `<img>` favicon. Defaults to a monogram of the name on a tint. |
| `children` | `React.ReactNode` | — | One line on why you read it (shown in the `list` variant; hidden in `grid`). |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to the link, which opens in a new tab. Translate it here. |

Also accepts every `li` prop.

### BlogrollFeeds

A row under the list: a short line plus OPML / RSS links. Add your own links as children.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `opml` | `string` | — | Link to an OPML file of the whole list, so readers can import it into their feed reader. |
| `rss` | `string` | — | Link to an RSS feed (e.g. of your own posts, or of the list's latest posts). |
| `label` | `React.ReactNode` | `"Follow them all in your reader"` | Text before the links. |

Also accepts every `div` prop.

## Used in templates

- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)



---

# Booking Card

> An “intro call” card with the host, meeting details and the next open slots as selectable chips. The button links to your scheduler with the chosen time.

Category: Contact · Registry item: `@portfolio-kit/booking-card` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/booking-card) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/booking-card.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/booking-card
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/booking-card.tsx` and the kit items it uses: `typography`.

npm dependencies: `lucide-react`.

shadcn/ui primitives: `avatar`, `button`.

## Usage

```tsx
import {
  BookingCard,
  BookingCardAction,
  BookingCardFooter,
  BookingCardHost,
  BookingCardSelection,
  BookingCardSlots,
  BookingCardTitle,
} from "@/components/portfolio/booking-card"

<BookingCard timeZone="Europe/Lisbon" duration={30}>
  <BookingCardHost name="Noa Vale" position="Independent product designer" />
  <BookingCardTitle>Let's talk about your project</BookingCardTitle>
  <BookingCardSlots slots={["2025-10-14T15:30:00Z", "2025-10-15T08:30:00Z"]} />
  <BookingCardFooter>
    <BookingCardSelection />
    <BookingCardAction href="https://cal.example.com/noa/intro" />
  </BookingCardFooter>
</BookingCard>
```

## Examples

### Demo

Shows your next open slots on the page. Pick one and the button links to your scheduler with that time.

```tsx
import {
  BookingCard,
  BookingCardAction,
  BookingCardDescription,
  BookingCardDetails,
  BookingCardFooter,
  BookingCardHost,
  BookingCardSelection,
  BookingCardSlots,
  BookingCardTimezone,
  BookingCardTitle,
} from "@/components/portfolio/booking-card"

// In production, fetch open slots from your scheduler (Cal.com, Calendly…) and drop `now`.
const now = new Date("2025-10-14T14:32:00Z")
const slots = [
  "2025-10-14T15:30:00Z",
  "2025-10-14T16:30:00Z",
  "2025-10-15T08:30:00Z",
  "2025-10-15T10:00:00Z",
  "2025-10-15T13:00:00Z",
  "2025-10-15T15:30:00Z",
  "2025-10-16T09:00:00Z",
  "2025-10-16T14:00:00Z",
]

export default function BookingCardDemo() {
  return (
    <BookingCard now={now} timeZone="Europe/Lisbon" duration={30} className="w-full max-w-lg">
      <BookingCardHost name="Noa Vale" position="Independent product designer" />
      <div className="flex flex-col gap-3">
        <BookingCardTitle>Let&apos;s talk about your project</BookingCardTitle>
        <BookingCardDescription>
          A relaxed 30 minutes to hear what you&apos;re building and see if we&apos;re a good fit. No prep needed.
        </BookingCardDescription>
        <BookingCardDetails medium="Google Meet" className="mt-1" />
      </div>
      <BookingCardSlots slots={slots} />
      <BookingCardTimezone />
      <BookingCardFooter>
        <BookingCardSelection />
        <BookingCardAction href="https://cal.example.com/noa/intro" />
      </BookingCardFooter>
    </BookingCard>
  )
}
```

### Compact

A smaller card for a sidebar or contact page: two days of slots on a 12-hour clock, in a time zone you choose.

```tsx
import { Phone } from "lucide-react"

import {
  BookingCard,
  BookingCardAction,
  BookingCardDetails,
  BookingCardFooter,
  BookingCardSlots,
  BookingCardTimezone,
  BookingCardTitle,
} from "@/components/portfolio/booking-card"

const now = new Date("2025-10-14T14:32:00Z")
const slots = [
  "2025-10-14T19:00:00Z",
  "2025-10-14T20:30:00Z",
  "2025-10-15T14:00:00Z",
  "2025-10-15T16:00:00Z",
  "2025-10-15T18:30:00Z",
  "2025-10-16T15:00:00Z",
]

export default function BookingCardCompact() {
  return (
    <BookingCard now={now} timeZone="America/New_York" duration={20} hour12 className="w-full max-w-md gap-5">
      <div className="flex flex-col gap-3">
        <BookingCardTitle>Quick question?</BookingCardTitle>
        <BookingCardDetails medium="Phone" mediumIcon={<Phone aria-hidden />} />
      </div>
      <BookingCardSlots slots={slots} days={2} perDay={3} legend="This week" />
      <BookingCardFooter>
        <BookingCardTimezone />
        <BookingCardAction href="https://cal.example.com/noa/quick" idleLabel="All times" />
      </BookingCardFooter>
    </BookingCard>
  )
}
```

### Fully Booked

When no slots are left, the card says so, the host's availability dot goes out and the button falls back to your full calendar.

```tsx
import {
  BookingCard,
  BookingCardAction,
  BookingCardDescription,
  BookingCardEyebrow,
  BookingCardFooter,
  BookingCardHost,
  BookingCardSlots,
  BookingCardTitle,
} from "@/components/portfolio/booking-card"

export default function BookingCardFullyBooked() {
  return (
    <BookingCard timeZone="Europe/Lisbon" className="w-full max-w-lg">
      <BookingCardHost name="Noa Vale" position="Independent product designer" available={false} />
      <div className="flex flex-col gap-3">
        <BookingCardEyebrow>Book an intro call</BookingCardEyebrow>
        <BookingCardTitle>Next openings are in November</BookingCardTitle>
        <BookingCardDescription>
          October is fully booked. The full calendar has everything from November onwards.
        </BookingCardDescription>
      </div>
      <BookingCardSlots slots={[]} empty="No open slots in the next few days." />
      <BookingCardFooter>
        <BookingCardAction href="https://cal.example.com/noa/intro" idleLabel="Open full calendar" />
      </BookingCardFooter>
    </BookingCard>
  )
}
```

## API Reference

### BookingCard

Root card. Holds the time zone, duration, locale and selected slot shared by every part.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `timeZone` | `string` | — | IANA time zone the slots are shown in, e.g. `"Europe/Lisbon"` (yours, named by `<BookingCardTimezone>`). Omit it to show the visitor's own zone: the server then renders UTC and the browser switches to the visitor's zone after hydration. Unknown zones fall back to UTC. |
| `duration` | `number` | `30` | Meeting length in minutes. Shown in `<BookingCardDetails>` and used for the selected range. |
| `hour12` | `boolean` | `false` | Show times on a 12-hour clock (`3:00 PM`) instead of 24-hour (`15:00`). |
| `locale` | `string` | `"en-US"` | BCP 47 locale for day and time names, e.g. `"de-DE"`. Keep it fixed (not the browser's) so server and browser agree. |
| `now` | `Date \| string` | — | Reference time for "Today"/"Tomorrow", hiding past slots and the zone offset. Without it, the server renders every slot with weekday names and the browser applies its own clock after hydration, so static pages never show a stale "Today". Pass a fixed date for screenshots and tests. |
| `value` | `string \| null` | — | Selected slot as an ISO string (controlled). |
| `defaultValue` | `string \| null` | `null` | Initially selected slot (uncontrolled). |
| `onValueChange` | `(iso: string \| null) => void` | — | Called with the chosen slot's ISO string (`toISOString()` form). |

Also accepts every `article` prop.

### BookingCardHost

Avatar, name and position of the host.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | The person you'd be meeting. |
| `position` | `string` | — | Job title or position, shown under the name. |
| `avatar` | `string` | — | Avatar image URL. |
| `initials` | `string` | — | Shown when there's no avatar image. Defaults to the name's initials. |
| `available` | `boolean` | `true` | Show the green "taking calls" dot on the avatar. Turn off when you're fully booked. |
| `availableLabel` | `string` | `"(taking calls)"` | What the dot means, read by screen readers after the name. |

Also accepts every `div` prop.

### BookingCardEyebrow

Small label above the title, e.g. "Book an intro call".

Also accepts every `p` prop.

### BookingCardTitle

The card's heading.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level. Use `h2` when the card is the main content of a section. |

Also accepts every `h3` prop.

### BookingCardDescription

A sentence or two on what the call is for.

Also accepts every `p` prop.

### BookingCardDetails

Duration (from the root) and meeting medium as small chips. Extra children are appended; wrap them in
`<BookingCardDetail>`. Named "Meeting details" for screen readers; pass `aria-label` to translate it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `medium` | `React.ReactNode` | `"Video call"` | Where you meet, e.g. `"Google Meet"`, `"Zoom"`, `"Phone"`. Pass `null` to hide it. |
| `mediumIcon` | `React.ReactNode` | — | Icon for the medium. Defaults to a video camera; pass e.g. `<Phone />` for calls. |
| `durationLabel` | `(minutes: number) => React.ReactNode` | `(minutes) => minutes + " min"` | Words the duration chip, e.g. `(minutes) => minutes + " Min."`. |

Also accepts every `ul` prop.

### BookingCardDetail

An extra chip inside `<BookingCardDetails>`, e.g. "Free" or "English / Português". Put an icon first if you like.

Also accepts every `li` prop.

### BookingCardSlots

Upcoming open slots grouped by day ("Today", "Tomorrow", "Thursday") as selectable time chips. It is one
radio group: Tab enters it, arrow keys move between times and select them, and the chosen time is filled
and ticked. Times are shown in the root's `timeZone`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `slots` (required) | `(string \| Date)[]` | — | Open start times (ISO strings or Dates). Past slots are skipped once a reference time is known. |
| `now` | `Date \| string` | — | Reference time. Defaults to the root's `now`, then the browser's clock after hydration. |
| `days` | `number` | `3` | How many upcoming days (that have open slots) to show. |
| `perDay` | `number` | `4` | Max time chips per day. |
| `legend` | `React.ReactNode` | `"Next available"` | Label above the slots. |
| `empty` | `React.ReactNode` | `"No open slots this week. Pick a time on the full calendar."` | Shown when no upcoming slots are left. |
| `todayLabel` | `string` | `"Today"` | Day label for today's slots. |
| `tomorrowLabel` | `string` | `"Tomorrow"` | Day label for tomorrow's slots. |

Also accepts every `fieldset` prop.

### BookingCardTimezone

"Times in Lisbon time (GMT+1)", derived from the root's `timeZone`. Pass `label` to translate it or children to word it yourself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `(city: string, offset: string) => React.ReactNode` | `(city, offset) => "Times in " + city + " time" + (offset ? " (" + offset + ")" : "")` | Words the default line, e.g. `(city) => "Heure de " + city`. `offset` is like `"GMT+1"`, or `""` until a reference time is known. |

Also accepts every `p` prop.

### BookingCardFooter

Bottom row above a divider, typically `<BookingCardSelection>` and `<BookingCardAction>`. Stacks on mobile.

Also accepts every `div` prop.

### BookingCardAction

The call to action: links to your scheduler, deep-linked to the selected slot. External (`http…`) URLs
open in a new tab and say so to screen readers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` (required) | `string` | — | Your scheduler URL (Cal.com, Calendly…). The selected slot is appended as a query param. |
| `param` | `string` | `"slot"` | Query param name for the selected slot. |
| `idleLabel` | `React.ReactNode` | `"See all times"` | Label when nothing is selected. |
| `selectedLabel` | `(slot: string) => React.ReactNode` | `(slot) => "Book " + slot` | Label once a slot is picked; receives the short day and time, e.g. `"Wed 11:00"`. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added to external links, which open in a new tab. |

Also accepts every `a` prop.

### BookingCardSelection

Live (announced) summary of the selected slot, e.g. "Wed, Oct 15 · 10:00–10:30".

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholder` | `React.ReactNode` | `"Pick a time above"` | Shown until a slot is picked. |

Also accepts every `p` prop.

## Used in templates

- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)



---

# Bookshelf

> Reading list as a shelf of standing covers that tilt on hover, or as a detailed list with status, rating and notes. Books without artwork get a generated cover.

Category: Content · Registry item: `@portfolio-kit/bookshelf` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/bookshelf) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/bookshelf.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/bookshelf
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/bookshelf.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import { Book, Bookshelf } from "@/components/portfolio/bookshelf"

<Bookshelf>
  <Book heading="The Quiet Interface" author="Maren Holt" status="reading" />
  <Book heading="Grid & Grain" author="Oona Lindqvist" status="finished" rating={5} cover={<img src="/books/grid-grain.jpg" alt="" />} />
  <Book heading="Weather for Designers" author="Ada Fairweather" status="want" />
</Bookshelf>
```

## Examples

### Demo

A reading list as a shelf of standing covers. Hover or tab to a book to tilt it out. Books without artwork get a generated cover with the title.

```tsx
import { Book, Bookshelf } from "@/components/portfolio/bookshelf"
import { GenerativeArt } from "@/components/portfolio/generative-art"

export default function BookshelfDemo() {
  return (
    <Bookshelf className="mx-auto max-w-2xl grid-cols-2 py-6 sm:grid-cols-4">
      <Book heading="The Quiet Interface" author="Maren Holt" status="reading" href="#the-quiet-interface" />
      <Book
        heading="Grid & Grain"
        author="Oona Lindqvist"
        status="finished"
        rating={5}
        note="The best book on design systems I've read, and it's really about organisations."
        cover={<GenerativeArt seed="grid-grain" variant="bauhaus" />}
        href="#grid-and-grain"
      />
      <Book heading="Systems of Small Parts" author="Idris Calloway" status="finished" rating={4} href="#systems-of-small-parts" />
      <Book
        heading="Weather for Designers"
        author="Ada Fairweather"
        status="want"
        cover={<GenerativeArt seed="weather" variant="waves" />}
        href="#weather-for-designers"
      />
    </Bookshelf>
  )
}
```

### List

A detailed reading log with cover, a short note, status and rating for each book. Suits a dedicated reading page.

```tsx
import type * as React from "react"

import { Book, Bookshelf } from "@/components/portfolio/bookshelf"
import { GenerativeArt } from "@/components/portfolio/generative-art"

const books: React.ComponentProps<typeof Book>[] = [
  {
    heading: "The Quiet Interface",
    author: "Maren Holt",
    status: "reading",
    note: "On calm technology and interfaces that stay out of the way. Chapter four alone is worth it.",
    href: "#the-quiet-interface",
  },
  {
    heading: "Systems of Small Parts",
    author: "Idris Calloway",
    status: "finished",
    rating: 5,
    note: "The best book on design systems I've read — and it's really about organisations.",
    href: "#systems-of-small-parts",
  },
  {
    heading: "Grid & Grain",
    author: "Oona Lindqvist",
    status: "finished",
    rating: 4,
    note: "A typographer's notebook. Beautifully printed; the margins alone taught me something.",
    cover: <GenerativeArt seed="grid-grain" variant="bauhaus" />,
    href: "#grid-and-grain",
  },
  {
    heading: "A Field Guide to Color",
    author: "Rosa Ventura",
    status: "want",
    note: "Recommended by three different people this month.",
  },
]

export default function BookshelfList() {
  return (
    <Bookshelf variant="list" aria-label="Reading log" className="mx-auto max-w-2xl">
      {books.map((book) => (
        <Book key={book.heading} {...book} />
      ))}
    </Bookshelf>
  )
}
```

### Currently Reading

The cover, status and rating parts used on their own, here as a small “on my nightstand” card for a home page or bento grid.

```tsx
import { BookCover, BookRating, BookStatusLabel } from "@/components/portfolio/bookshelf"
import { typography } from "@/lib/typography"

export default function BookshelfCurrentlyReading() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-5 rounded-2xl border bg-card p-5 text-card-foreground shadow-card md:p-6">
      <p className={typography.eyebrow}>On my nightstand</p>
      <div className="flex items-center gap-5">
        <BookCover heading="The Quiet Interface" author="Maren Holt" className="w-20 shrink-0" />
        <div className="flex min-w-0 flex-col gap-1.5">
          <BookStatusLabel status="reading" />
          <h3 className={typography.heading}>The Quiet Interface</h3>
          <p className="text-sm text-muted-foreground">Maren Holt</p>
        </div>
      </div>
      <div className="flex items-center justify-between gap-4 border-t pt-4">
        <p className="text-sm text-muted-foreground">
          Last finished: <span className="text-foreground">Grid &amp; Grain</span>
        </p>
        <BookRating rating={4} />
      </div>
    </div>
  )
}
```

## API Reference

### Bookshelf

The list of books (a `<ul>` labelled "Books"; override with `aria-label`). `shelf` stands the
covers side by side on a ledge (they tilt out on hover and keyboard focus) and wraps onto more
rows on narrow screens; `list` is a detailed reading log with notes. Children are `Book`s.
Override the columns with `className` (e.g. `grid-cols-2 sm:grid-cols-4`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"shelf" \| "list"` | `"shelf"` | `shelf`: covers standing side by side, for a visual reading list. `list`: rows with status, rating and notes, for reviews. |

Also accepts every `ul` prop.

### BookCover

A 2:3 book cover with a spine crease. Without `cover`, it typesets the title on a color derived
from the title, so the same book always gets the same cover. Decorative (`aria-hidden`), so put
the title in text next to it. Size it with a width class (`w-20`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `string` | — | Book title. Required (or the deprecated `title`). |
| `title` | `string` | — | Deprecated alias of `heading`. |
| `author` | `string` | — | Printed under the title on generated covers (hidden when the cover is very small). |
| `cover` | `React.ReactNode` | — | Image URL, or any node (e.g. `<GenerativeArt />`). Omit for a generated cover. |

Also accepts every `div` prop.

### BookStatusLabel

Small mono label with an icon for a book's reading status.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` (required) | `"reading" \| "finished" \| "want"` | — | `reading` (highlighted dot), `finished` (check) or `want` (hollow dot). |
| `children` | `React.ReactNode` | — | Custom label, e.g. "Re-reading" or a translation. Defaults to "Reading", "Finished" or "Want to read". |

Also accepts every `span` prop.

### BookRating

Five stars, filled up to `rating`. Announced as "Rated 4 out of 5"; pass `aria-label` to translate it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rating` (required) | `number` | — | 0–5, rounded to whole stars. |

Also accepts every `span` prop.

### Book

One book: a cover plus its title, author, status and rating, laid out for the parent `Bookshelf` variant.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `string` | — | Book title. Required (or the deprecated `title`). |
| `title` | `string` | — | Deprecated alias of `heading`. |
| `author` | `string` | — | Author name(s), shown under the title and on a generated cover. |
| `cover` | `React.ReactNode` | — | Image URL or node (e.g. `<GenerativeArt />`). Omit for a generated, typeset cover. |
| `status` | `"reading" \| "finished" \| "want"` | — | Reading status shown under the title (shelf) or at the end of the row (list). |
| `rating` | `number` | — | 1–5 stars. `0` or omitted hides the rating. |
| `note` | `React.ReactNode` | — | A line or two about the book. Shown in full in the `list` variant; to cap long notes, clamp them from the `Book`: `className="[&_[data-slot=book-note]]:line-clamp-3"`. On the shelf it's read to screen readers (and describes the title link), and a string note is also the native tooltip. |
| `href` | `string` | — | Makes the whole book a link (via its title). External URLs open in a new tab, marked with ↗. |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the title. Use `h4` when the shelf sits under an `h3`. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to links that open in a new tab. Translate it here. |

Also accepts every `li` prop.

## Used in templates

- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Brand Icons

> Dependency-free social/brand glyphs (GitHub, X, LinkedIn, Dribbble…) plus URL → brand detection.

Category: Utilities · Registry item: `@portfolio-kit/brand-icons` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/brand-icons) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/brand-icons.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/brand-icons
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/brand-icons.tsx`.

## Usage

```tsx
import { brands, brandNames, isBrandName, detectBrand, BrandIcon } from "@/components/portfolio/brand-icons"
```

## Examples

### Demo

Single-path brand glyphs that inherit `currentColor` and size with the text — no icon font, no extra dependency.

```tsx
import { BrandIcon, brands, type BrandName } from "@/components/portfolio/brand-icons"

const featured: BrandName[] = ["github", "linkedin", "dribbble", "figma", "behance", "x", "bluesky", "youtube"]

export default function BrandIconsDemo() {
  return (
    <ul role="list" className="grid w-full max-w-md grid-cols-4 gap-2">
      {featured.map((name) => (
        <li
          key={name}
          className="flex flex-col items-center gap-2.5 rounded-xl border bg-card px-2 py-4 text-card-foreground"
        >
          <BrandIcon name={name} className="size-6" />
          <span className="font-mono text-[0.6875rem] text-muted-foreground">{brands[name].title.split(" ")[0]}</span>
        </li>
      ))}
    </ul>
  )
}
```

### Detect from URL

`detectBrand()` maps a profile URL to its icon, so an “Elsewhere” list only needs the links you already have.

```tsx
import { ArrowUpRight, Globe } from "lucide-react"

import { BrandIcon, brands, detectBrand } from "@/components/portfolio/brand-icons"
import { typography } from "@/lib/typography"

const profiles = [
  "https://github.com/example",
  "https://www.linkedin.com/in/example",
  "https://read.cv/example",
  "https://example.com/journal",
]

export default function BrandIconsDetectBrand() {
  return (
    <div className="w-full max-w-sm">
      <p className={typography.eyebrow}>Elsewhere</p>
      <ul role="list" className="mt-4 divide-y border-y">
        {profiles.map((href) => {
          const brand = detectBrand(href)
          const url = new URL(href)
          return (
            <li key={href}>
              <a
                href={href}
                target="_blank"
                rel="noopener noreferrer"
                className="group flex items-center gap-3 rounded-sm py-3 text-sm outline-none transition-colors focus-visible:ring-[3px] focus-visible:ring-ring/50"
              >
                <span className="flex size-8 shrink-0 items-center justify-center rounded-pill border text-muted-foreground transition-colors group-hover:text-foreground">
                  {brand ? <BrandIcon name={brand} className="size-4" /> : <Globe aria-hidden className="size-4" />}
                </span>
                <span className="font-medium">{brand ? brands[brand].title : "Website"}</span>
                <span className="ml-auto truncate font-mono text-xs text-muted-foreground">
                  {url.hostname.replace(/^www\./, "")}
                  {url.pathname}
                </span>
                <ArrowUpRight
                  aria-hidden
                  className="size-3.5 shrink-0 text-muted-foreground transition-transform duration-300 ease-smooth motion-reduce:transition-none group-hover:-translate-y-0.5 group-hover:translate-x-0.5"
                />
                <span className="sr-only"> (opens in a new tab)</span>
              </a>
            </li>
          )
        })}
      </ul>
    </div>
  )
}
```

### In Buttons

Drop a glyph into any button or link — it picks up the text color, so it works on solid and outline styles alike.

```tsx
import { cn } from "@/lib/utils"
import { buttonVariants } from "@/components/ui/button"
import { BrandIcon } from "@/components/portfolio/brand-icons"

export default function BrandIconsInButtons() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      <a href="#github" className={cn(buttonVariants({ size: "lg" }), "rounded-pill")}>
        <BrandIcon name="github" /> Star on GitHub
      </a>
      <a href="#dribbble" className={cn(buttonVariants({ variant: "outline", size: "lg" }), "rounded-pill")}>
        <BrandIcon name="dribbble" /> Follow on Dribbble
      </a>
      <a
        href="#youtube"
        aria-label="YouTube"
        className={cn(buttonVariants({ variant: "outline", size: "icon-lg" }), "rounded-pill")}
      >
        <BrandIcon name="youtube" />
      </a>
    </div>
  )
}
```

## API Reference

### BrandIcon

A brand logo as a 24×24 SVG in `currentColor`, sized like a lucide icon (`size-4` etc. via `className`;
`1em` otherwise). Decorative by default; give it a `title` when it is the only content of a link or button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `BrandName` | — | Which logo, e.g. `"github"`. Use `detectBrand(href)` to detect it from a profile link, or `isBrandName()` to check a string. An unknown name renders nothing. |
| `title` | `string` | — | Accessible label, for an icon that stands alone (no visible text next to it). When omitted (and no `aria-label`/`aria-labelledby` is passed) the icon is decorative and hidden from screen readers. |

Other props are forwarded to the root element.

## Used in templates

- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)



---

# Case Study Header

> Opening of a case study: back link, display title, summary, a ruled facts grid (client, role, timeline, live site) and a cover image.

Category: Work · Registry item: `@portfolio-kit/case-study-header` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/case-study-header) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/case-study-header.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/case-study-header
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/case-study-header.tsx` and the kit items it uses: `media`, `typography`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import {
  CaseStudyBack,
  CaseStudyCover,
  CaseStudyEyebrow,
  CaseStudyHeader,
  CaseStudyMeta,
  CaseStudyMetaItem,
  CaseStudySummary,
  CaseStudyTitle,
} from "@/components/portfolio/case-study-header"

<CaseStudyHeader>
  <CaseStudyBack href="/work" />
  <CaseStudyEyebrow>Case study · 2025</CaseStudyEyebrow>
  <CaseStudyTitle>Lumen: one system for eleven products</CaseStudyTitle>
  <CaseStudySummary>How four UI libraries became one token-driven platform.</CaseStudySummary>
  <CaseStudyMeta>
    <CaseStudyMetaItem label="Client">Halcyon Labs</CaseStudyMetaItem>
    <CaseStudyMetaItem label="Role">Design lead</CaseStudyMetaItem>
  </CaseStudyMeta>
  <CaseStudyCover caption="The Lumen component explorer.">
    <img src="/work/lumen-cover.jpg" alt="The Lumen component explorer" />
  </CaseStudyCover>
</CaseStudyHeader>
```

## Examples

### Demo

The top of a case study page: back link, title, summary, facts grid and cover.

```tsx
import {
  CaseStudyBack,
  CaseStudyCover,
  CaseStudyEyebrow,
  CaseStudyHeader,
  CaseStudyMeta,
  CaseStudyMetaItem,
  CaseStudySummary,
  CaseStudyTitle,
} from "@/components/portfolio/case-study-header"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Container } from "@/components/portfolio/section"

export default function CaseStudyHeaderDemo() {
  return (
    <Container className="py-12 md:py-20">
      <CaseStudyHeader>
        <CaseStudyBack href="#work" />
        <CaseStudyEyebrow>Case study · 2025</CaseStudyEyebrow>
        <CaseStudyTitle>Lumen: one system for eleven products</CaseStudyTitle>
        <CaseStudySummary>
          How we replaced four drifting UI libraries with a single token-driven platform — and cut the time to ship a new
          screen from weeks to days.
        </CaseStudySummary>
        <CaseStudyMeta>
          <CaseStudyMetaItem label="Client">Halcyon Labs</CaseStudyMetaItem>
          <CaseStudyMetaItem label="Role">Design lead</CaseStudyMetaItem>
          <CaseStudyMetaItem label="Timeline">
            <time dateTime="2024-03">Mar 2024</time> – <time dateTime="2025-01">Jan 2025</time>
          </CaseStudyMetaItem>
          <CaseStudyMetaItem label="Services">
            <ul role="list">
              <li>Design systems</li>
              <li>Front-end architecture</li>
            </ul>
          </CaseStudyMetaItem>
          <CaseStudyMetaItem label="Live site" href="https://lumen.example.com">
            lumen.example.com
          </CaseStudyMetaItem>
        </CaseStudyMeta>
        <CaseStudyCover caption="Fig. 0 — The Lumen component explorer, dark mode.">
          <GenerativeArt seed="lumen" variant="interface" hue={250} label="The Lumen component explorer" />
        </CaseStudyCover>
      </CaseStudyHeader>
    </Container>
  )
}
```

### Bleed Cover

A cover that spans the full page width. Its full-width parent is a size container that clips horizontal overflow.

```tsx
import {
  CaseStudyBack,
  CaseStudyCover,
  CaseStudyEyebrow,
  CaseStudyHeader,
  CaseStudyMeta,
  CaseStudyMetaItem,
  CaseStudySummary,
  CaseStudyTitle,
} from "@/components/portfolio/case-study-header"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Container } from "@/components/portfolio/section"

export default function CaseStudyHeaderBleedCover() {
  return (
    <div className="@container overflow-x-clip">
      <Container className="pt-12 md:pt-20">
        <CaseStudyHeader>
          <CaseStudyBack href="#work">Back to projects</CaseStudyBack>
          <CaseStudyEyebrow>Product design · 2025</CaseStudyEyebrow>
          <CaseStudyTitle>Tidewater</CaseStudyTitle>
          <CaseStudySummary>
            Real-time grid monitoring for coastal wind farms — dense data, calm interface.
          </CaseStudySummary>
          <CaseStudyMeta>
            <CaseStudyMetaItem label="Client">Tidewater Energy</CaseStudyMetaItem>
            <CaseStudyMetaItem label="Role">Product design</CaseStudyMetaItem>
            <CaseStudyMetaItem label="Year">
              <time dateTime="2025">2025</time>
            </CaseStudyMetaItem>
          </CaseStudyMeta>
          <CaseStudyCover bleed ratio="wide">
            <GenerativeArt seed="tidewater" variant="interface" hue={195} label="The Tidewater control-room dashboard" />
          </CaseStudyCover>
        </CaseStudyHeader>
      </Container>
    </div>
  )
}
```

### Text Only

No cover, in a narrow column, for case studies that are mostly writing.

```tsx
import {
  CaseStudyBack,
  CaseStudyEyebrow,
  CaseStudyHeader,
  CaseStudyMeta,
  CaseStudyMetaItem,
  CaseStudySummary,
  CaseStudyTitle,
} from "@/components/portfolio/case-study-header"
import { Container } from "@/components/portfolio/section"

export default function CaseStudyHeaderTextOnly() {
  return (
    <Container size="sm" className="py-12 md:py-20">
      <CaseStudyHeader>
        <CaseStudyBack href="#writing">All case studies</CaseStudyBack>
        <CaseStudyEyebrow>Brand &amp; web · 2024</CaseStudyEyebrow>
        <CaseStudyTitle className="lg:text-7xl">Giving a research tool the voice of a field notebook</CaseStudyTitle>
        <CaseStudySummary>
          Identity and marketing site for Fieldnote, a note-taking app built for researchers.
        </CaseStudySummary>
        <CaseStudyMeta>
          <CaseStudyMetaItem label="Client">Fieldnote Inc.</CaseStudyMetaItem>
          <CaseStudyMetaItem label="Duration">6 weeks</CaseStudyMetaItem>
          <CaseStudyMetaItem label="Live site" href="https://fieldnote.example.com">
            fieldnote.example.com
          </CaseStudyMetaItem>
        </CaseStudyMeta>
      </CaseStudyHeader>
    </Container>
  )
}
```

## API Reference

### CaseStudyHeader

The `<header>` of a case study page: stacks its parts in order with a steady rhythm.

Also accepts every `header` prop.

### CaseStudyBack

"← All work" link back to the index.

Also accepts every `a` prop.

### CaseStudyEyebrow

Small label above the title, e.g. "Case study · 2025".

Also accepts every `p` prop.

### CaseStudyTitle

The project name or headline, at display size. Renders the page's `<h1>` by default; long words break instead of overflowing.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h1" \| "h2"` | `"h1"` | Heading level. Keep `h1`: a case study page should have exactly one, and this is it. Use `h2` only when the page already has its own `h1`. |

Also accepts every `h1` prop.

### CaseStudySummary

One or two sentences on the problem and the result.

Also accepts every `p` prop.

### CaseStudyMeta

Facts grid, as a `<dl>` (each `CaseStudyMetaItem` is a `<dt>`/`<dd>` pair). Every item gets its own top hairline, so it reads as a ruled table at any column count.

Also accepts every `dl` prop.

### CaseStudyMetaItem

One fact in the grid: a label over its value.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `React.ReactNode` | — | The fact's name, e.g. "Client" or "Timeline" (rendered as the `<dt>`). |
| `children` (required) | `React.ReactNode` | — | The value (the `<dd>`): text, `<time>` elements or a short `<ul>` of services. |
| `href` | `string` | — | Turns the value into a link. External URLs open in a new tab and say so to screen readers; long URLs wrap instead of being cut off. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added when `href` opens in a new tab. Translate it here. |

Also accepts every `div` prop.

### CaseStudyCover

The hero image, video or artwork, built on `Media` (so it takes `ratio`, `radius` and `caption`).
With `bleed`, give a full-width parent `@container overflow-x-clip`. The cover spans that size
container, so it lines up with the window edges even next to a classic scrollbar, and the clip
stops sideways scroll. Without a size container it spans the viewport (`100vw`, which includes the
scrollbar).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | `"photo" \| "video" \| "square" \| "portrait" \| "wide" \| "tall" \| "auto"` | `"video"` | Aspect ratio of the frame: `photo` 4:3, `video` 16:9, `square`, `portrait` 4:5, `tall` 3:4, `wide` 21:9. `auto` sets no ratio: the image or video keeps its own shape (pass `width`/`height` in `imgProps` or `videoProps` to reserve the space before it loads), or size the frame yourself with `className`/`frameClassName` (`aspect-*`, `size-full`). Artwork alone has no size of its own. |
| `radius` | `"default" \| "none" \| "lg" \| "full"` | — | Corner radius: `default` follows the theme, `lg` is larger, `full` makes a circle (use with `square`), `none` is square. |
| `bordered` | `boolean` | — | Draw a hairline border, for screenshots with white edges on a white page. |
| `src` | `string` | — | Image URL. Loads lazily and fades in from a blur once decoded (at once under reduced motion). |
| `alt` | `string` | — | Text alternative for the image or video. Describe what the media shows when it carries content; leave it empty (the default) when it's decorative or the caption or nearby text already says it. |
| `priority` | `boolean` | — | Mark the image as the page's main, above-the-fold image (the LCP element): it loads eagerly with high fetch priority and shows at once, without the blur-up fade. |
| `video` | `string` | — | Video source. Plays muted and looped while on screen and the tab is visible. Under reduced motion, reduced data or Save-Data it doesn't start; it shows `poster` and controls instead. |
| `poster` | `string` | — | Poster frame shown before the video plays (and instead of it under reduced motion or data saving). |
| `zoom` | `boolean` | `false` | Scale the media when the frame (or any ancestor `.group`) is hovered. Off for reduced motion. |
| `caption` | `React.ReactNode` | — | Caption under the frame. When set, Media renders a `<figure>` with a `<figcaption>`; otherwise a single `<div>`. |
| `frameClassName` | `string` | — | Classes for the frame itself. With a `caption`, `className` styles the outer `<figure>`, so use this for a per-breakpoint ratio: `ratio="auto" frameClassName="aspect-[4/5] sm:aspect-video"`. |
| `children` | `React.ReactNode` | — | Artwork (e.g. `<GenerativeArt />`) or overlays rendered inside the frame, on top of any image or video. |
| `imgProps` | `Omit<React.ComponentProps<"img">, "src" \| "alt">` | — | Extra props for the `<img>`: `sizes` and `srcSet` for responsive images, `width`/`height`… |
| `videoProps` | `Omit<React.ComponentProps<"video">, "src" \| "poster">` | — | Extra props for the `<video>` (`controls`, `preload`, tracks…). With `controls`, the visitor's play and pause win. |
| `bleed` | `boolean` | `false` | Break out of the container and span the full page width. Put `@container overflow-x-clip` on a full-width parent: the cover then matches that parent exactly (the viewport minus any scrollbar). |

Other props are forwarded to the root element.

## Used in templates

- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)



---

# Case Study Section

> Case study chapter with a sticky numbered label, styled prose, pull quotes, outcome metrics and figures that can span the label column.

Category: Work · Registry item: `@portfolio-kit/case-study-section` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/case-study-section) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/case-study-section.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/case-study-section
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/case-study-section.tsx` and the kit items it uses: `media`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  CaseStudyFigure,
  CaseStudyMetric,
  CaseStudyMetrics,
  CaseStudyProse,
  CaseStudyPullQuote,
  CaseStudySection,
  CaseStudySectionContent,
  CaseStudySectionLabel,
} from "@/components/portfolio/case-study-section"

<CaseStudySection aria-labelledby="challenge">
  <CaseStudySectionLabel index={1} id="challenge">Challenge</CaseStudySectionLabel>
  <CaseStudySectionContent>
    <CaseStudyProse>
      <p>Eleven products had forked one component library into four buttons and six date pickers.</p>
    </CaseStudyProse>
    <CaseStudyFigure src="/work/audit.jpg" alt="The component audit" label="Fig. 1" caption="Every button we found." />
    <CaseStudyPullQuote author="Lena Ortiz" position="VP Product">It finally feels like one product.</CaseStudyPullQuote>
    <CaseStudyMetrics>
      <CaseStudyMetric value="−38%" label="Time to ship a screen" />
      <CaseStudyMetric value="100%" label="Focus-visible coverage" />
    </CaseStudyMetrics>
  </CaseStudySectionContent>
</CaseStudySection>
```

## Examples

### Demo

A chapter whose numbered label stays pinned while the prose (headings, lists, quotes, code) scrolls past.

```tsx
import {
  CaseStudyProse,
  CaseStudySection,
  CaseStudySectionContent,
  CaseStudySectionLabel,
} from "@/components/portfolio/case-study-section"
import { Container } from "@/components/portfolio/section"

export default function CaseStudySectionDemo() {
  return (
    <Container className="py-6 md:py-10">
      <CaseStudySection aria-labelledby="challenge">
        <CaseStudySectionLabel index={1} id="challenge">
          Challenge
        </CaseStudySectionLabel>
        <CaseStudySectionContent>
          <CaseStudyProse>
            <p>
              Halcyon had grown to eleven products in four years. Each team had forked the original component library,
              and by the time we arrived there were <strong>four buttons, six date pickers and no shared tokens</strong>.
              Shipping a new screen meant re-deciding every spacing value.
            </p>
            <p>
              Our brief was simple to state and hard to do: make the products feel like one family without freezing any
              team in place. We started with an audit — every screen, every colour, every <code>z-index</code>.
            </p>
            <h3>What we found</h3>
            <ul role="list">
              <li>312 unique colour values, 41 of them near-duplicates of the brand blue.</li>
              <li>Focus styles missing on 60% of interactive elements.</li>
              <li>
                A spacing scale that existed only in a <a href="#audit">Figma file</a> nobody opened.
              </li>
            </ul>
            <blockquote>The problem wasn’t the components. It was that nobody owned the decisions behind them.</blockquote>
            <p>From there we set three principles, in order of priority:</p>
            <ol role="list">
              <li>Tokens are an API — version them like one.</li>
              <li>Accessibility is a default, not a review step.</li>
              <li>Every component ships with docs, tests and a migration path.</li>
            </ol>
          </CaseStudyProse>
        </CaseStudySectionContent>
      </CaseStudySection>
    </Container>
  )
}
```

### Outcome

Close a case study with the numbers that moved and a pull quote from the client.

```tsx
import {
  CaseStudyMetric,
  CaseStudyMetrics,
  CaseStudyProse,
  CaseStudyPullQuote,
  CaseStudySection,
  CaseStudySectionContent,
  CaseStudySectionLabel,
} from "@/components/portfolio/case-study-section"
import { Container } from "@/components/portfolio/section"

const quote = {
  text: "Our design system finally feels like one thing — and the teams actually want to use it.",
  author: "Ines Carvalho",
  role: "VP Product, Halcyon Labs",
}

export default function CaseStudySectionOutcome() {
  return (
    <Container className="py-6 md:py-10">
      <CaseStudySection aria-labelledby="outcome">
        <CaseStudySectionLabel index={4} id="outcome">
          Outcome
        </CaseStudySectionLabel>
        <CaseStudySectionContent>
          <CaseStudyProse>
            <p>
              Six months after launch, every product runs on Lumen. The numbers below compare the quarter before
              migration to the quarter after.
            </p>
          </CaseStudyProse>
          <CaseStudyMetrics>
            <CaseStudyMetric value="+38%" label="Activation" detail="New workspaces, first week" />
            <CaseStudyMetric value="4×" label="Faster UI delivery" detail="Median screen, idea → prod" />
            <CaseStudyMetric value="−62%" label="CSS shipped" />
            <CaseStudyMetric value="100" label="Lighthouse a11y" />
          </CaseStudyMetrics>
          <CaseStudyPullQuote author={quote.author} position={quote.role}>
            {quote.text}
          </CaseStudyPullQuote>
        </CaseStudySectionContent>
      </CaseStudySection>
    </Container>
  )
}
```

### Figures

Captioned figures that fill the text column, or go `wide` to break out across the label column.

```tsx
import {
  CaseStudyFigure,
  CaseStudyProse,
  CaseStudySection,
  CaseStudySectionContent,
  CaseStudySectionLabel,
} from "@/components/portfolio/case-study-section"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Container } from "@/components/portfolio/section"

export default function CaseStudySectionFigures() {
  return (
    <Container className="py-6 md:py-10">
      <CaseStudySection aria-labelledby="process">
        <CaseStudySectionLabel index={2} id="process">
          Process
        </CaseStudySectionLabel>
        <CaseStudySectionContent>
          <CaseStudyProse>
            <p>
              We prototyped in code from week one. Every token change rendered across all eleven products in a single
              preview deploy, which made debates short and concrete.
            </p>
          </CaseStudyProse>
          <CaseStudyFigure label="Fig. 1" caption="Token pipeline: one source, eleven themes, three platforms.">
            <GenerativeArt seed="lumen-pipeline" variant="bauhaus" label="Diagram of the token pipeline" />
          </CaseStudyFigure>
          <CaseStudyFigure
            size="wide"
            ratio="wide"
            label="Fig. 2"
            caption="The component explorer — every component, in every theme, side by side."
          >
            <GenerativeArt seed="lumen-components" variant="interface" hue={250} label="Wide screenshot of the component explorer" />
          </CaseStudyFigure>
        </CaseStudySectionContent>
      </CaseStudySection>
    </Container>
  )
}
```

### With Table of Contents

The `stacked` layout puts the label above the content, so chapters can sit beside a scrollspy table of contents.

```tsx
import {
  CaseStudyProse,
  CaseStudySection,
  CaseStudySectionContent,
  CaseStudySectionLabel,
} from "@/components/portfolio/case-study-section"
import { Container } from "@/components/portfolio/section"
import { TableOfContents } from "@/components/portfolio/table-of-contents"

const chapters = [
  {
    id: "context",
    title: "Context",
    body: "Tidewater operators watched forty turbines across six browser tabs. Alarms arrived by email, minutes after the fact, and nobody trusted the numbers on screen.",
  },
  {
    id: "approach",
    title: "Approach",
    body: "We shadowed three control-room shifts, then rebuilt the dashboard around a single question: what needs a human right now? Everything else became quiet by default.",
  },
  {
    id: "results",
    title: "Results",
    body: "Median time to acknowledge an alarm fell from nine minutes to under one, and the six tabs became one screen that operators leave open all day.",
  },
]

export default function CaseStudySectionWithTableOfContents() {
  return (
    <Container className="grid pb-[40vh] lg:grid-cols-[11rem_minmax(0,1fr)] lg:gap-x-16">
      <aside className="hidden lg:block">
        <TableOfContents
          items={chapters.map(({ id, title }) => ({ id, label: title }))}
          offset={24}
          className="sticky top-6 pt-14 md:pt-20"
        />
      </aside>
      <div className="min-w-0">
        {chapters.map((chapter, i) => (
          <CaseStudySection key={chapter.id} id={chapter.id} layout="stacked" aria-labelledby={`${chapter.id}-title`}>
            <CaseStudySectionLabel index={i + 1} id={`${chapter.id}-title`}>
              {chapter.title}
            </CaseStudySectionLabel>
            <CaseStudySectionContent>
              <CaseStudyProse>
                <p>{chapter.body}</p>
              </CaseStudyProse>
            </CaseStudySectionContent>
          </CaseStudySection>
        ))}
      </div>
    </Container>
  )
}
```

## API Reference

### CaseStudySection

A chapter. In the `split` layout the label column has a fixed width (`--cs-label`) so wide
figures can break out of the content column by exactly that much. The sticky label stops
6rem below the top of the viewport, clear of a typical fixed site header; raise it for a taller
header with `--cs-sticky-top`, e.g. `className="[--cs-sticky-top:8rem]"`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `layout` | `"split" \| "stacked"` | `"split"` | `split`: a sticky numbered label beside the content from `md` up. `stacked`: label above the content, for pages with their own side rail (e.g. a table of contents). |

Also accepts every `section` prop.

### CaseStudySectionLabel

Label column: index + chapter name (rendered as a heading). Sticky in the `split` layout, where it
stays pinned below the site header (`--cs-sticky-top`) and stops at the end of its chapter.
`id` goes on the heading, so the section can point `aria-labelledby` at it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number \| string` | — | Chapter number: `1` → "01". |
| `as` | `"h2" \| "h3"` | `"h2"` | Heading level of the label. `h2` under a `CaseStudyTitle` (the page's `h1`); `h3` when chapters sit inside your own `h2` sections. Prose headings inside should go one level lower. |

Also accepts every `div` prop.

### CaseStudySectionContent

The chapter body: prose, figures, metrics and quotes, evenly spaced.

Also accepts every `div` prop.

### CaseStudyProse

Long-form copy. Style plain HTML (p, h3, h4, ul, ol, blockquote, a, code, strong, hr) without extra
classes. Lines are capped at about 70 characters (`34em`) for comfortable reading; long words and
URLs wrap instead of overflowing.

Also accepts every `div` prop.

### CaseStudyPullQuote

A large quote from a client or user, set in the heading font: a `<figure>` with the `<blockquote>` and its attribution in a `<figcaption>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `author` | `React.ReactNode` | — | Who said it. |
| `position` | `React.ReactNode` | — | The author's job title or position, shown after the name. |

Also accepts every `figure` prop.

### CaseStudyMetrics

Grid of outcome numbers. Every metric gets its own top hairline, so it reads as a ruled table at any column count.

Also accepts every `dl` prop.

### CaseStudyMetric

One outcome: a big number over what it measures.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `React.ReactNode` | — | The number, e.g. "+38%". |
| `label` (required) | `React.ReactNode` | — | What it measures, e.g. "Activation". |
| `detail` | `React.ReactNode` | — | Optional context under the label. |

Also accepts every `div` prop.

### CaseStudyFigure

Image, video or artwork with a numbered caption. `size="wide"` also spans the label column.
`className` styles the `<figure>`; the remaining props (`src`, `alt`, `ratio`…) go to the media frame.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `video` | `string` | — | Video source. Plays muted and looped while on screen and the tab is visible. Under reduced motion, reduced data or Save-Data it doesn't start; it shows `poster` and controls instead. |
| `children` | `React.ReactNode` | — | Artwork (e.g. `<GenerativeArt />`) or overlays rendered inside the frame, on top of any image or video. |
| `ratio` | `"photo" \| "video" \| "square" \| "portrait" \| "wide" \| "tall" \| "auto"` | `"video"` | Aspect ratio of the frame: `photo` 4:3, `video` 16:9, `square`, `portrait` 4:5, `tall` 3:4, `wide` 21:9. `auto` sets no ratio: the image or video keeps its own shape (pass `width`/`height` in `imgProps` or `videoProps` to reserve the space before it loads), or size the frame yourself with `className`/`frameClassName` (`aspect-*`, `size-full`). Artwork alone has no size of its own. |
| `radius` | `"default" \| "none" \| "lg" \| "full"` | `"lg"` | Corner radius: `default` follows the theme, `lg` is larger, `full` makes a circle (use with `square`), `none` is square. |
| `bordered` | `boolean` | — | Draw a hairline border, for screenshots with white edges on a white page. |
| `src` | `string` | — | Image URL. Loads lazily and fades in from a blur once decoded (at once under reduced motion). |
| `alt` | `string` | — | Text alternative for the image or video. Describe what the media shows when it carries content; leave it empty (the default) when it's decorative or the caption or nearby text already says it. |
| `poster` | `string` | — | Poster frame shown before the video plays (and instead of it under reduced motion or data saving). |
| `priority` | `boolean` | — | Mark the image as the page's main, above-the-fold image (the LCP element): it loads eagerly with high fetch priority and shows at once, without the blur-up fade. |
| `zoom` | `boolean` | — | Scale the media when the frame (or any ancestor `.group`) is hovered. Off for reduced motion. |
| `frameClassName` | `string` | — | Class for the media frame, e.g. a per-breakpoint aspect ratio: `ratio="auto" frameClassName="aspect-[5/4] sm:aspect-video"`. |
| `imgProps` | `Omit<React.ComponentProps<"img">, "src" \| "alt">` | — | Extra props for the `<img>`: `sizes` and `srcSet` for responsive images, `width`/`height`… |
| `videoProps` | `Omit<React.ComponentProps<"video">, "src" \| "poster">` | — | Extra props for the `<video>` (`controls`, `preload`, tracks…). With `controls`, the visitor's play and pause win. |
| `size` | `"column" \| "wide"` | `"column"` | `column`: fills the content column. `wide`: also spans the label column from `md` up, for hero shots and wide mockups. |
| `caption` | `React.ReactNode` | — | Caption under the media. |
| `label` | `React.ReactNode` | — | Figure label rendered before the caption, e.g. "Fig. 2". |

Other props are forwarded to the root element.

## Used in templates

- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)



---

# Changelog

> A dated "what changed" log for a portfolio or product page: releases with version, date and optional permalink, and changes labelled Added, Changed or Fixed in words.

Category: Content · Registry item: `@portfolio-kit/changelog` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/changelog) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/changelog.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/changelog
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/changelog.tsx` and the kit items it uses: `format`, `tag-list`, `typography`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  Changelog,
  ChangelogChange,
  ChangelogChanges,
  ChangelogEntry,
} from "@/components/portfolio/changelog"

<Changelog label="Changelog">
  <ChangelogEntry version="2.4" date="2026-09-28" heading="Autumn refresh" latest anchor>
    <ChangelogChanges>
      <ChangelogChange kind="added">Dark mode for every page.</ChangelogChange>
      <ChangelogChange kind="fixed">Video posters no longer flash on load.</ChangelogChange>
    </ChangelogChanges>
  </ChangelogEntry>
  <ChangelogEntry version="2.3" date="2026-08-02">
    <ChangelogChanges>
      <ChangelogChange kind="changed">Case studies open faster.</ChangelogChange>
    </ChangelogChanges>
  </ChangelogEntry>
</Changelog>
```

## Examples

### Demo

A portfolio's changelog page: releases newest first with version, date and permalink, and each change labelled Added, Changed or Fixed.

```tsx
import {
  Changelog,
  ChangelogChange,
  ChangelogChanges,
  ChangelogEntry,
} from "@/components/portfolio/changelog"

export default function ChangelogDemo() {
  return (
    <Changelog label="Changelog" anchor className="mx-auto w-full max-w-3xl">
      <ChangelogEntry version="3.2" date="2026-09-28" heading="Autumn refresh" latest>
        <ChangelogChanges>
          <ChangelogChange kind="added">
            A <a href="https://example.com/lab">lab page</a> for experiments that never became projects.
          </ChangelogChange>
          <ChangelogChange kind="changed">Case studies load their images as you scroll.</ChangelogChange>
          <ChangelogChange kind="fixed">The menu no longer traps focus after closing on mobile.</ChangelogChange>
        </ChangelogChanges>
      </ChangelogEntry>
      <ChangelogEntry version="3.1" date="2026-07-14">
        <ChangelogChanges>
          <ChangelogChange kind="added">Dark mode, following your system setting.</ChangelogChange>
          <ChangelogChange kind="removed">The autoplaying showreel on the home page.</ChangelogChange>
        </ChangelogChanges>
      </ChangelogEntry>
      <ChangelogEntry version="3.0" date="2026-03-02" heading="A quieter site">
        <p>Rebuilt from scratch with fewer pages, bigger images and no tracking.</p>
      </ChangelogEntry>
    </Changelog>
  )
}
```

### Site log

A designer's running site log: the footer's VersionLabel on top, then plain-bullet entries with calendar versions.

```tsx
import {
  Changelog,
  ChangelogChange,
  ChangelogChanges,
  ChangelogEntry,
} from "@/components/portfolio/changelog"
import { VersionLabel } from "@/components/portfolio/version-label"
import { typography } from "@/lib/typography"

export default function ChangelogSiteLog() {
  return (
    <div className="mx-auto flex w-full max-w-3xl flex-col gap-8">
      <header className="flex flex-col gap-3">
        <h2 className={typography.title}>Site log</h2>
        <VersionLabel variant="pill" dot className="self-start" version="2026.1328" updated="2026-08-09" />
      </header>
      <Changelog label="Site log" datePreset="long">
        <ChangelogEntry version="2026.1328" date="2026-08-09">
          <ChangelogChanges>
            <ChangelogChange>New type: the headings are now set in a grotesk with a little more ink.</ChangelogChange>
            <ChangelogChange>Moved the archive to its own page.</ChangelogChange>
          </ChangelogChanges>
        </ChangelogEntry>
        <ChangelogEntry version="2026.1102" date="2026-04-12">
          <ChangelogChanges>
            <ChangelogChange>Added the Kestrel jewellery series to the index.</ChangelogChange>
          </ChangelogChanges>
        </ChangelogEntry>
      </Changelog>
    </div>
  )
}
```

### What's new

The stacked variant in a card on a product page: the last two releases and a link to the full changelog.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import {
  Changelog,
  ChangelogChange,
  ChangelogChanges,
  ChangelogEntry,
} from "@/components/portfolio/changelog"
import { typography } from "@/lib/typography"

export default function ChangelogWhatsNew() {
  return (
    <section
      aria-labelledby="whats-new-title"
      className="flex w-md max-w-full flex-col gap-6 rounded-2xl border bg-card p-5 shadow-card md:p-6"
    >
      <h2 id="whats-new-title" className={typography.eyebrow}>
        What&apos;s new in Driftnote
      </h2>
      <Changelog variant="stacked" headingLevel="h3" datePreset="short">
        <ChangelogEntry version="1.8" date="2026-09-30" latest>
          <ChangelogChanges>
            <ChangelogChange kind="added">Export notes as Markdown.</ChangelogChange>
            <ChangelogChange kind="fixed">Sync no longer duplicates pinned notes.</ChangelogChange>
          </ChangelogChanges>
        </ChangelogEntry>
        <ChangelogEntry version="1.7" date="2026-09-12">
          <ChangelogChanges>
            <ChangelogChange kind="security">Sessions expire after 30 days of inactivity.</ChangelogChange>
          </ChangelogChanges>
        </ChangelogEntry>
      </Changelog>
      <ArrowLink href="https://example.com/driftnote/changelog">Full changelog</ArrowLink>
    </section>
  )
}
```

## API Reference

### Changelog

An ordered list of releases, newest first. Put `ChangelogEntry`s inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"split" \| "stacked"` | `"split"` | `split`: version and date in a sticky column beside the notes (from `md`), for a full changelog page. `stacked`: one column, for a "what's new" card or sidebar. |
| `label` | `string` | — | Accessible name for the list, e.g. "Changelog" or "What's new". |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading element for each release's version. Pick the level below the section's heading. |
| `anchor` | `boolean` | `false` | Give every release an `id` and make its version a link to it, so releases can be shared (`/changelog#v2-4`). Entries can override it. |
| `datePreset` | `"year" \| "full" \| "month-year" \| "short" \| "long" \| "short-padded" \| "full-padded"` | `"full"` | `formatDate` preset for release dates: `full` "Sep 28, 2026", `long`, `month-year`… |
| `locale` | `string` | `"en-US"` | BCP 47 locale for dates. Translate the kind words with `labels`. |
| `labels` | `Partial<ChangelogLabels>` | — | Words for each change kind and the latest badge: `{ added, changed, fixed, removed, security, latest }`. |

Also accepts every `ol` prop.

### ChangelogEntry

One release: version heading, date, optional name and badge, then its notes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `version` (required) | `string \| number` | — | Release version, rendered as the release heading: `"2.4"` → "v2.4", `"2026.1328"` → "v2026.1328". Values starting with a letter ("Edition 3", "beta") are shown as-is. |
| `children` | `React.ReactNode` | — | Notes: a sentence of prose, `ChangelogChanges`, or both. |
| `date` | `DateInput` | — | Release date: a `Date`, ISO string (`"2026-09-28"`) or timestamp, rendered as `<time>`. |
| `heading` | `React.ReactNode` | — | Optional release name, e.g. "Autumn refresh", shown above the notes. |
| `latest` | `boolean` | `false` | Mark the newest release with a "Latest" badge. |
| `anchor` | `boolean` | — | Permalink for this release (overrides the list's `anchor`). Uses `id` when you pass one, else one made from the version ("v2-4"). |

Also accepts every `li` prop.

### ChangelogChanges

The list of changes in a release (`<ul>`). Its two-column grid lines the change text up after the
widest kind chip, so longer translated words don't push single rows out of line.

Also accepts every `ul` prop.

### ChangelogChange

One change. With a `kind`, it starts with a labelled chip ("Added"); the chips share a width so the text lines up.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `"added" \| "changed" \| "fixed" \| "removed" \| "security"` | — | What kind of change, shown as a word in a chip (never colour alone): `added`, `changed`, `fixed`, `removed` or `security`. Leave it out for a plain bullet. |

Also accepts every `li` prop.

### type ChangelogLabels

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `security` (required) | `string` | — |  |
| `added` (required) | `string` | — |  |
| `changed` (required) | `string` | — |  |
| `fixed` (required) | `string` | — |  |
| `removed` (required) | `string` | — |  |
| `latest` (required) | `string` | — |  |

## Used in templates

- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)



---

# Circular Text

> A rotating badge of text set around a circle (“Available for work · Available for work ·”) with a slot in the middle for an icon or link. Pauses on hover and keyboard focus; can speed up or reverse with scrolling.

Category: Effects · Registry item: `@portfolio-kit/circular-text` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/circular-text) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/circular-text.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/circular-text
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/circular-text.tsx` and the kit items it uses: `use-composed-refs`, `use-in-view`, `use-reduced-motion`.

## Usage

```tsx
import {
  CircularText,
  CircularTextCenter,
} from "@/components/portfolio/circular-text"

<CircularText text="Available for work" repeat={2} className="size-32">
  <CircularTextCenter className="bg-highlight text-highlight-foreground">
    <span aria-hidden>↗</span>
  </CircularTextCenter>
</CircularText>
```

## Examples

### Demo

The classic spot: an “available for work” badge pinned to the corner of your portrait, turning slowly around an arrow that links to contact. It pauses while hovered or focused.

```tsx
import { ArrowUpRight } from "lucide-react"

import { CircularText, CircularTextCenter } from "@/components/portfolio/circular-text"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { typography } from "@/lib/typography"

export default function CircularTextDemo() {
  return (
    <section className="mx-auto grid w-full max-w-4xl items-center gap-12 py-6 sm:grid-cols-[minmax(0,1fr)_auto] sm:gap-10 md:gap-16">
      <div className="flex flex-col gap-5">
        <p className={typography.eyebrow}>Product designer · Lisbon</p>
        <h1 className="font-heading text-3xl leading-[1.05] text-balance md:text-5xl">Mara Lindqvist designs calm software for busy people.</h1>
        <p className={`${typography.lead} max-w-md`}>Eight years across fintech and health. Now taking projects for spring.</p>
      </div>

      <div className="relative mx-auto mb-10 w-52 sm:mb-0 sm:w-48 md:w-64">
        <div className="aspect-[4/5] overflow-hidden rounded-2xl border shadow-card">
          <GenerativeArt seed="mara-portrait" variant="portrait" label="Portrait of Mara" />
        </div>
        {/* Pinned over the corner on a solid disc so the ring stays crisp over any photo. */}
        <a
          href="#contact"
          aria-label="Available for work: get in touch"
          className="group/badge absolute -bottom-8 -left-8 rounded-full bg-background outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 md:-left-12"
        >
          <CircularText text="Available for work" repeat={2} className="size-28 md:size-36">
            <CircularTextCenter className="bg-highlight text-highlight-foreground">
              <ArrowUpRight
                aria-hidden
                className="transition-transform duration-300 ease-smooth group-hover/badge:rotate-45 motion-reduce:transition-none"
              />
            </CircularTextCenter>
          </CircularText>
        </a>
      </div>
    </section>
  )
}
```

### Scroll Boost

Pinned in a hero corner, it spins faster as you scroll down and winds backwards as you scroll up.

```tsx
import { CircularText } from "@/components/portfolio/circular-text"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { typography } from "@/lib/typography"

export default function CircularTextScrollBoost() {
  return (
    <div className="mx-auto flex max-w-5xl flex-col gap-10 px-5 py-16 sm:px-6 md:px-8">
      <div className="relative flex flex-col gap-6">
        <p className={typography.eyebrow}>Motion designer</p>
        <h1 className={`${typography.display} max-w-3xl`}>Interfaces that feel alive</h1>
        <CircularText
          text="Scroll to explore"
          separator=" ✦ "
          repeat={2}
          duration={14}
          scrollBoost
          className="fixed right-6 bottom-6 z-10 size-28 rounded-full bg-background/85 backdrop-blur-sm text-foreground md:right-10 md:bottom-10 md:size-32"
        >
          <span className="size-[46%] overflow-hidden rounded-full">
            <GenerativeArt seed="scroll-badge" variant="orb" grain={false} />
          </span>
        </CircularText>
      </div>
      {["alpha", "beta", "gamma"].map((seed) => (
        <div key={seed} className="aspect-[16/9] overflow-hidden rounded-2xl border">
          <GenerativeArt seed={seed} variant="interface" />
        </div>
      ))}
    </div>
  )
}
```

## API Reference

### CircularText

A square badge (size it with `className`, e.g. `size-32`). The ring text is an SVG `textPath`
whose `textLength` equals the circumference, so any phrase fits exactly with no gap at the seam;
a phrase too long for the ring is set smaller instead of overlapping. Screen readers hear the
phrase once. With reduced motion it's still, and it pauses while scrolled out of view.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` (required) | `string` | — | The phrase. It's repeated `repeat` times around the circle, joined by `separator`, and read once by screen readers. |
| `separator` | `string` | `" · "` | Placed after every repetition, so the loop is seamless. |
| `repeat` | `number` | `2` | How many times the phrase goes around. Short phrases read better with 3, long ones with 1. |
| `duration` | `number` | `20` | Seconds per full turn. Lower is faster. |
| `direction` | `"clockwise" \| "counterclockwise"` | `"clockwise"` | Turn clockwise or counter-clockwise. |
| `pauseOnHover` | `boolean` | `true` | Pause while the pointer is over the badge (mouse and trackpad only). It always pauses while it, or a link around it, has keyboard focus. |
| `paused` | `boolean` | `false` | Stop the rotation where it is. A rotation that runs longer than five seconds next to other content needs a way to pause it (WCAG 2.2.2): keep this in state and toggle it from your own button. |
| `scrollBoost` | `boolean` | `false` | Spin faster while the page scrolls, and backwards while scrolling up. |
| `children` | `React.ReactNode` | — | The center: an icon, avatar or a link. |

Also accepts every `div` prop.

### CircularTextCenter

Optional round center: a filled disc for an icon or arrow, sized to sit inside the ring.

Also accepts every `div` prop.



---

# Code Window

> Code for case studies and developer portfolios: file tabs, a language label, copy, line numbers, highlighted and diff lines, and soft wrap. Plain text by default; bring your own highlighter.

Category: Content · Registry item: `@portfolio-kit/code-window` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/code-window) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/code-window.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/code-window
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/code-window.tsx` and the kit items it uses: `use-composed-refs`, `use-copy-to-clipboard`.

npm dependencies: `class-variance-authority`, `lucide-react`, `radix-ui`.

## Usage

```tsx
import {
  CodeWindow,
  CodeWindowCopy,
  CodeWindowFile,
  CodeWindowHeader,
  CodeWindowTab,
  CodeWindowTabs,
} from "@/components/portfolio/code-window"

<CodeWindow lineNumbers>
  <CodeWindowHeader language="TypeScript">
    <CodeWindowTabs>
      <CodeWindowTab value="tokens.ts">tokens.ts</CodeWindowTab>
      <CodeWindowTab value="button.tsx">button.tsx</CodeWindowTab>
    </CodeWindowTabs>
    <CodeWindowCopy />
  </CodeWindowHeader>
  <CodeWindowFile value="tokens.ts" code={`export const radius = "0.75rem"`} />
  <CodeWindowFile value="button.tsx" code={`export function Button() {}`} />
</CodeWindow>
```

## Examples

### Demo

Two files from a case study in tabs, with line numbers, a highlighted line, a language label and a copy button.

```tsx
import {
  CodeWindow,
  CodeWindowCopy,
  CodeWindowFile,
  CodeWindowHeader,
  CodeWindowTab,
  CodeWindowTabs,
} from "@/components/portfolio/code-window"

const tokens = `import { defineTokens } from "@halcyon/tokens"

export const color = defineTokens({
  accent: { light: "oklch(0.55 0.2 260)", dark: "oklch(0.72 0.16 260)" },
  surface: { light: "oklch(0.99 0 0)", dark: "oklch(0.17 0 0)" },
  // Semantic names are the public API. Primitives can change freely.
  danger: { light: "oklch(0.58 0.21 25)", dark: "oklch(0.7 0.18 25)" },
})
`

const button = `import { color } from "./tokens"

export function Button({ tone = "accent", ...props }) {
  return <button style={{ background: color[tone] }} {...props} />
}
`

export default function CodeWindowDemo() {
  return (
    <CodeWindow lineNumbers className="mx-auto w-full max-w-2xl">
      <CodeWindowHeader language="TypeScript">
        <CodeWindowTabs>
          <CodeWindowTab value="tokens.ts">tokens.ts</CodeWindowTab>
          <CodeWindowTab value="button.tsx">button.tsx</CodeWindowTab>
        </CodeWindowTabs>
        <CodeWindowCopy />
      </CodeWindowHeader>
      <CodeWindowFile value="tokens.ts" code={tokens} highlight="6-7" />
      <CodeWindowFile value="button.tsx" code={button} />
    </CodeWindow>
  )
}
```

### Diff

Show what changed in a case study: `diff` tints lines starting with + and −, and copying gives the new code without the markers.

```tsx
import { CodeWindow, CodeWindowCopy, CodeWindowFile, CodeWindowHeader } from "@/components/portfolio/code-window"

const change = ` export async function loadPage(slug: string) {
-  const page = await db.pages.find({ slug })
-  const blocks = await db.blocks.findMany({ page: page.id })
+  const [page, blocks] = await Promise.all([
+    db.pages.find({ slug }),
+    db.blocks.findMany({ pageSlug: slug }),
+  ])
   return render(page, blocks)
 }`

export default function CodeWindowDiff() {
  return (
    <CodeWindow tone="card" className="mx-auto w-full max-w-2xl">
      <CodeWindowHeader heading="app/pages/load.ts — one round trip instead of two" language="diff">
        <CodeWindowCopy />
      </CodeWindowHeader>
      <CodeWindowFile code={change} diff label="Diff of load.ts" />
    </CodeWindow>
  )
}
```

### With a highlighter

Bring any syntax highlighter: pass one rendered node per line as `highlighted` (e.g. from shiki's `codeToTokens`). This example uses a tiny hand-written tokenizer instead of a dependency.

```tsx
import * as React from "react"

import { CodeWindow, CodeWindowCopy, CodeWindowFile, CodeWindowHeader } from "@/components/portfolio/code-window"

const code = `const pages = await fetchPages() // cached for an hour
for (const page of pages) {
  if (page.draft) continue
  await render(page, { theme: "editorial" })
}`

// Stand-in for a real highlighter. With shiki, map `codeToTokens(code, { lang, theme }).tokens`
// to one <span> per line with a <span style={{ color: token.color }}> per token.
const rules: [RegExp, string][] = [
  [/^\/\/.*/, "text-muted-foreground italic"],
  [/^"[^"]*"/, "text-highlight-ink"],
  [/^\b(const|for|of|if|continue|await)\b/, "text-foreground font-semibold"],
  [/^\b[a-zA-Z_]\w*(?=\()/, "text-success"],
]

function tokenize(line: string) {
  const out: React.ReactNode[] = []
  let rest = line
  let key = 0
  while (rest) {
    const rule = rules.find(([re]) => re.test(rest))
    if (rule) {
      const [match] = rest.match(rule[0])!
      out.push(
        <span key={key++} className={rule[1]}>
          {match}
        </span>
      )
      rest = rest.slice(match.length)
    } else {
      out.push(rest[0])
      rest = rest.slice(1)
    }
  }
  return <span key={line} className="text-foreground/80">{out}</span>
}

export default function CodeWindowHighlighter() {
  const highlighted = React.useMemo(() => code.split("\n").map(tokenize), [])
  return (
    <CodeWindow chrome={false} className="mx-auto w-full max-w-2xl">
      <CodeWindowHeader heading="build.ts" language="ts">
        <CodeWindowCopy />
      </CodeWindowHeader>
      <CodeWindowFile code={code} highlighted={highlighted} lineNumbers />
    </CodeWindow>
  )
}
```

## API Reference

### CodeWindow

The window. Put a `CodeWindowHeader` (with `CodeWindowTab`s for several files) and one or more
`CodeWindowFile`s inside. With several files it's a tab list; the `value` of each file matches its tab.
For a single file, omit the tabs and give the header a `heading`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"dark" \| "card"` | `"dark"` | `dark`: an editor-like dark window in every theme. `card`: uses the page's card colors, so it's light in light mode. |
| `chrome` | `boolean` | `true` | Show the three window dots in the header. Turn off for a flatter, documentation look. |
| `lineNumbers` | `boolean` | `false` | Number every line. Can be overridden per file on `CodeWindowFile`. |
| `defaultWrap` | `boolean` | `false` | Start with soft wrap on. Users can toggle it with the wrap button. |

Also accepts every `Tabs.Root` prop.

### CodeWindowHeader

Top bar: window dots, the heading or tabs (children), the language label and actions such as `CodeWindowCopy`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `React.ReactNode` | — | File name or caption for a single-file window, e.g. `"tokens.ts"`. Omit when you use tabs. Long captions wrap. |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `language` | `React.ReactNode` | — | Short language label on the right, e.g. `"TypeScript"`. |
| `wrapToggle` | `boolean` | `true` | Show the soft-wrap toggle. |
| `wrapLabel` | `string` | `"Wrap long lines"` | Accessible name and tooltip of the soft-wrap toggle. Translate it here. |

Also accepts every `div` prop.

### CodeWindowTabs

The tab list for several files. Put `CodeWindowTab`s inside, inside the header. Its accessible name defaults to "Files"; pass `aria-label` to translate it.

Also accepts every `Tabs.List` prop.

### CodeWindowTab

One file tab. Its `value` matches a `CodeWindowFile`.

Also accepts every `Tabs.Trigger` prop.

### CodeWindowCopy

Copies the code, with a check mark for a moment afterwards. When the browser refuses (permissions,
insecure page), it says so next to the button instead. Both outcomes are announced to screen readers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Text to copy. Inside a tabbed window, omit it to copy the visible file. |
| `label` | `string` | `"Copy code"` | Accessible name and tooltip of the button. |
| `copiedLabel` | `string` | `"Copied to clipboard"` | Announced after a successful copy. |
| `failedLabel` | `string` | `"Couldn’t copy — select the text"` | Shown next to the button (and announced) when the browser refuses to copy. |

Also accepts every `button` prop.

### CodeWindowFile

One file's code. Pass `code` as a string; it's split into lines for numbering, highlighting and diffs.
To use a syntax highlighter, also pass `highlighted` (one rendered node per line) and the kit handles
the rest. The region scrolls sideways (or wraps) and is keyboard-focusable.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `code` (required) | `string` | — | The code as plain text. Also what `CodeWindowCopy` copies. |
| `value` | `string` | `"file"` | Tab value (usually the file name). Required when there are several files. |
| `highlighted` | `React.ReactNode[]` | — | Pre-highlighted lines from your highlighter, one node per line (same count as `code`'s lines), e.g. from shiki's `codeToTokens`. Without it, the code is shown as plain text. |
| `highlight` | `LineSpec` | — | Emphasize lines: `"3"`, `"2-4,7"` or `[2, 3]`. |
| `diff` | `boolean` | `false` | Treat lines starting with `+` / `-` as a diff: added and removed lines are tinted and marked in the gutter, and the marker is dropped from the copied text. |
| `lineNumbers` | `boolean` | — | Number the lines. Defaults to the window's `lineNumbers`. |
| `label` | `string` | — | Accessible name of the scrollable code area. Defaults to the tab value, or "Code". |
| `diffLabels` | `{ added: string; removed: string }` | `{ added: "Added: ", removed: "Removed: " }` | Screen-reader prefixes for diff lines. Translate them here. |

Also accepts every `Tabs.Content` prop.



---

# Color Swatches

> A project’s palette for case studies: named swatches with hex and OKLCH values you click to copy, WCAG contrast labels, and grid, strip or proportional (by usage) layouts.

Category: Work · Registry item: `@portfolio-kit/color-swatches` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/color-swatches) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/color-swatches.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/color-swatches
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/color-swatches.tsx` and the kit items it uses: `use-copy-to-clipboard`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  ColorSwatch,
  ColorSwatches,
} from "@/components/portfolio/color-swatches"

<ColorSwatches>
  <ColorSwatch name="Harbor" purpose="Primary" color="#1F3A5F" />
  <ColorSwatch name="Tide" purpose="Accent" color="#3FA7A0" />
  <ColorSwatch name="Sand" purpose="Surface" color="#F4EDE1" />
</ColorSwatches>
```

## Examples

### Demo

A brand palette at a glance: each color’s role, hex and OKLCH values you click to copy, and how well it carries text.

```tsx
import { ColorSwatch, ColorSwatches } from "@/components/portfolio/color-swatches"

const palette = [
  { name: "Harbor", purpose: "Primary", color: "#1F3A5F" },
  { name: "Tide", purpose: "Accent", color: "#3FA7A0" },
  { name: "Signal", purpose: "Alert", color: "#F2A541" },
  { name: "Sand", purpose: "Surface", color: "#F4EDE1" },
] as const

export default function ColorSwatchesDemo() {
  return (
    <ColorSwatches className="mx-auto w-full max-w-4xl">
      {palette.map((swatch) => (
        <ColorSwatch key={swatch.name} {...swatch} />
      ))}
    </ColorSwatches>
  )
}
```

### Proportional

`layout="proportional"` sizes each color by how much of the product it covers, which says more about a brand than a row of equal chips.

```tsx
import { ColorSwatch, ColorSwatches } from "@/components/portfolio/color-swatches"

export default function ColorSwatchesProportional() {
  return (
    <ColorSwatches layout="proportional" formats={["hex"]} className="mx-auto w-full max-w-4xl">
      <ColorSwatch name="Paper" purpose="Surface" color="#F6F1E7" usage={58} />
      <ColorSwatch name="Ink" purpose="Text" color="#1C1B19" usage={24} />
      <ColorSwatch name="Kiln" purpose="Primary" color="#C4553A" usage={12} />
      <ColorSwatch name="Glaze" purpose="Accent" color="#6F8F7A" usage={6} />
    </ColorSwatches>
  )
}
```

### Strip

`layout="strip"`: one continuous band, details printed on each color in whichever of black or white reads best. Click a value to copy it.

```tsx
import { ColorSwatch, ColorSwatches } from "@/components/portfolio/color-swatches"

export default function ColorSwatchesStrip() {
  return (
    <ColorSwatches layout="strip" formats={["hex", "rgb", "oklch"]} className="mx-auto w-full max-w-4xl">
      <ColorSwatch name="Midnight" purpose="Base" color="#141B2D" />
      <ColorSwatch name="Orbit" purpose="Primary" color="#5B5BD6" />
      <ColorSwatch name="Flare" purpose="Accent" color="#FF7A59" />
      <ColorSwatch name="Mist" purpose="Surface" color="#E8ECF4" />
    </ColorSwatches>
  )
}
```

### In a case study

The palette chapter of a case study: a short rationale, then every color with its role, copyable values and how it holds up for text.

```tsx
import {
  CaseStudyProse,
  CaseStudySection,
  CaseStudySectionContent,
  CaseStudySectionLabel,
} from "@/components/portfolio/case-study-section"
import { ColorSwatch, ColorSwatches } from "@/components/portfolio/color-swatches"
import { Container } from "@/components/portfolio/section"

const palette = [
  { name: "Harbor", purpose: "Primary", color: "#1F3A5F" },
  { name: "Tide", purpose: "Accent", color: "#3FA7A0" },
  { name: "Signal", purpose: "Alert", color: "#F2A541" },
  { name: "Sand", purpose: "Surface", color: "#F4EDE1" },
] as const

export default function ColorSwatchesInACaseStudy() {
  return (
    <Container className="py-10 md:py-16">
      <CaseStudySection aria-labelledby="palette">
        <CaseStudySectionLabel index={3} id="palette">
          Palette
        </CaseStudySectionLabel>
        <CaseStudySectionContent className="flex flex-col gap-10">
          <CaseStudyProse>
            <p>
              Tidewater&rsquo;s operators work night shifts in dim control rooms, so the palette starts dark and calm.
              Color is reserved for meaning: teal for healthy output, amber for anything that needs a human.
            </p>
          </CaseStudyProse>
          <ColorSwatches>
            {palette.map((swatch) => (
              <ColorSwatch key={swatch.name} {...swatch} />
            ))}
          </ColorSwatches>
        </CaseStudySectionContent>
      </CaseStudySection>
    </Container>
  )
}
```

## API Reference

### ColorSwatches

The palette (`<ul>`). Put `<ColorSwatch>`es inside (as direct children), in the order you want them
read. The `proportional` layout draws them twice: as bands in a bar (decorative, labelled only where
there's room) and as a legend underneath with every value.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `layout` | `"grid" \| "strip" \| "proportional"` | `"grid"` | `grid`: cards with a chip and details underneath. `strip`: one continuous band, details on the colors. `proportional`: one bar whose bands are sized by each swatch’s `usage`, with a legend of values underneath. |
| `formats` | `("hex" \| "rgb" \| "oklch")[]` | `["hex", "oklch"]` | Which values to list, in order: `"hex"` (`#1F3A5F`), `"rgb"` (`rgb(31 58 95)`), `"oklch"` (`oklch(0.347 0.073 256.7)`). Each copies on click. |
| `labels` | `Partial<ColorSwatchesLabels>` | — | Built-in text (copy buttons, contrast labels), for translations: `{ copy, copied, copiedStatus, copyFailed, copyFailedStatus, contrast, contrastTitle, white, black, aaLarge, fail }`. |

Also accepts every `ul` prop.

### ColorSwatch

One color: a chip (or band segment), its name and role, copyable values and a contrast label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` (required) | `string` | — | The color as hex (`#1F3A5F` or `#abc`). Values, contrast and OKLCH are computed from it. Text on the swatch uses whichever of black or white contrasts more; mid-tones may reach only "AA Large". |
| `name` (required) | `string` | — | Its name in the brand, e.g. "Harbor". |
| `purpose` | `string` | — | What it's for, e.g. "Primary", "Surface", "Accent". |
| `usage` | `number` | — | Share of the palette, in %. Sizes the segment in the `proportional` layout and is shown there. |

Also accepts every `li` prop.

### type ColorSwatchesLabels

Built-in text, for translations. `{format}`, `{value}`, `{ink}` and `{ratio}` are replaced.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `copy` (required) | `string` | — | Accessible name of a value's copy button. |
| `copied` (required) | `string` | — | Flashed in place of the value after copying. |
| `copiedStatus` (required) | `string` | — | Announced after copying. |
| `copyFailed` (required) | `string` | — | Shown in place of the value when the browser refuses to copy. |
| `copyFailedStatus` (required) | `string` | — | Announced when the browser refuses to copy. |
| `contrast` (required) | `string` | — | Read before the contrast ratio. |
| `contrastTitle` (required) | `string` | — | Tooltip of the contrast label. |
| `white` (required) | `string` | — | `{ink}` for white text. |
| `black` (required) | `string` | — | `{ink}` for black text. |
| `aaLarge` (required) | `string` | — | Rating for 3:1 to 4.5:1. |
| `fail` (required) | `string` | — | Rating below 3:1. |

## Used in templates

- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)



---

# Command Menu

> A ⌘K palette for jumping to pages, projects and actions, with fuzzy search, grouped results and keyboard hints. Pass data or compose the parts yourself.

Category: Navigation · Registry item: `@portfolio-kit/command-menu` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/command-menu) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/command-menu.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/command-menu
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/command-menu.tsx` and the kit items it uses: `kbd`, `typography`.

npm dependencies: `class-variance-authority`, `cmdk`, `lucide-react`, `radix-ui`.

## Usage

```tsx
import {
  CommandMenu,
  CommandMenuContent,
  CommandMenuGroup,
  CommandMenuItem,
  CommandMenuTrigger,
} from "@/components/portfolio/command-menu"

<CommandMenu>
  <CommandMenuTrigger />
  <CommandMenuContent>
    <CommandMenuGroup heading="Pages">
      <CommandMenuItem href="/work">Work</CommandMenuItem>
      <CommandMenuItem href="/about">About</CommandMenuItem>
    </CommandMenuGroup>
    <CommandMenuGroup heading="Contact">
      <CommandMenuItem href="mailto:hello@example.com">Email me</CommandMenuItem>
    </CommandMenuGroup>
  </CommandMenuContent>
</CommandMenu>
```

## Examples

### Demo

A ⌘K palette for jumping between pages, projects and quick actions. Press ⌘K / Ctrl K or click the trigger.

```tsx
import { Briefcase, Copy, FileText, Home, Mail, Moon, PenLine, User } from "lucide-react"

import { BrandIcon } from "@/components/portfolio/brand-icons"
import { CommandMenu, CommandMenuTrigger, type CommandMenuGroupData } from "@/components/portfolio/command-menu"
import { GenerativeArt } from "@/components/portfolio/generative-art"

const groups: CommandMenuGroupData[] = [
  {
    heading: "Pages",
    items: [
      { label: "Home", icon: <Home />, href: "#top" },
      { label: "Work", icon: <Briefcase />, href: "#work" },
      { label: "About", icon: <User />, href: "#about" },
      { label: "Writing", icon: <PenLine />, href: "#writing" },
    ],
  },
  {
    heading: "Projects",
    items: [
      {
        label: "Lumen",
        href: "#lumen",
        keywords: ["design system", "tokens", "react"],
        icon: <GenerativeArt seed="lumen" variant="interface" />,
      },
      {
        label: "Tidewater",
        href: "#tidewater",
        keywords: ["dashboard", "data viz"],
        icon: <GenerativeArt seed="tidewater" variant="interface" />,
      },
      {
        label: "Fieldnote",
        href: "#fieldnote",
        keywords: ["brand", "website"],
        icon: <GenerativeArt seed="fieldnote" variant="bauhaus" />,
      },
    ],
  },
  {
    heading: "Actions",
    items: [
      {
        label: "Copy email address",
        icon: <Copy />,
        keywords: ["contact", "mail"],
        onSelect: () => void navigator.clipboard?.writeText("hello@example.com"),
      },
      {
        label: "Toggle dark mode",
        icon: <Moon />,
        keywords: ["theme", "appearance"],
        onSelect: () => document.documentElement.classList.toggle("dark"),
      },
      { label: "Download résumé", icon: <FileText />, keywords: ["cv", "pdf"], href: "#resume" },
    ],
  },
  {
    heading: "Elsewhere",
    items: [
      { label: "GitHub", icon: <BrandIcon name="github" />, href: "https://github.com/example" },
      { label: "LinkedIn", icon: <BrandIcon name="linkedin" />, href: "https://www.linkedin.com/in/example" },
      { label: "Email", icon: <Mail />, href: "mailto:hello@example.com" },
    ],
  },
]

export default function CommandMenuDemo() {
  return (
    <CommandMenu groups={groups}>
      <CommandMenuTrigger className="w-72" />
    </CommandMenu>
  )
}
```

### In a Header

A search-field trigger on desktop and an icon button on phones. Both open the same menu.

```tsx
import { Briefcase, Mail, PenLine, User } from "lucide-react"

import { cn } from "@/lib/utils"
import { CommandMenu, CommandMenuTrigger, type CommandMenuGroupData } from "@/components/portfolio/command-menu"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { KbdShortcut } from "@/components/portfolio/kbd"
import { Container } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

const groups: CommandMenuGroupData[] = [
  {
    heading: "Pages",
    items: [
      { label: "Work", icon: <Briefcase />, href: "#work" },
      { label: "About", icon: <User />, href: "#about" },
      { label: "Writing", icon: <PenLine />, href: "#writing" },
      { label: "Contact", icon: <Mail />, href: "#contact" },
    ],
  },
  {
    heading: "Projects",
    items: [
      { label: "Lumen", href: "#lumen", keywords: ["design system"], icon: <GenerativeArt seed="lumen" variant="interface" /> },
      { label: "Tidewater", href: "#tidewater", keywords: ["dashboard"], icon: <GenerativeArt seed="tidewater" variant="interface" /> },
      { label: "Orbit", href: "#orbit", keywords: ["open source"], icon: <GenerativeArt seed="orbit" variant="rings" /> },
    ],
  },
]

export default function CommandMenuInHeader() {
  return (
    <div>
      <header className="border-b">
        <Container className="flex h-16 items-center justify-between gap-4">
          <a
            href="#top"
            className="shrink-0 rounded-md font-heading text-base outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
          >
            Noa Vale
          </a>
          <CommandMenu groups={groups} placeholder="Search pages and projects…">
            <CommandMenuTrigger label="Search…" className="w-56 max-sm:hidden" />
            <CommandMenuTrigger variant="icon" label="Search" className="sm:hidden" />
          </CommandMenu>
        </Container>
      </header>
      <Container className="flex flex-col gap-4 py-20 md:py-28">
        <p className={typography.eyebrow}>
          Press <KbdShortcut keys={["mod", "k"]} /> anywhere
        </p>
        <h1 className={cn(typography.title, "max-w-3xl")}>I design and build calm, fast interfaces for ambitious product teams.</h1>
      </Container>
    </div>
  )
}
```

### Composed

Compose the content yourself: a search over blog posts with reading times, a custom empty state and its own ⌘J shortcut.

```tsx
import { PenLine, SearchX } from "lucide-react"

import {
  CommandMenu,
  CommandMenuContent,
  CommandMenuGroup,
  CommandMenuItem,
  CommandMenuTrigger,
} from "@/components/portfolio/command-menu"

const posts = [
  { title: "Motion that explains itself", slug: "motion", tags: ["animation", "easing"], readingTime: "6 min" },
  { title: "Tokens are an API, not a palette", slug: "tokens", tags: ["design systems", "css"], readingTime: "9 min" },
  { title: "The case for boring navigation", slug: "navigation", tags: ["ux", "information architecture"], readingTime: "4 min" },
  { title: "Designing for the second visit", slug: "second-visit", tags: ["retention", "onboarding"], readingTime: "7 min" },
]

export default function CommandMenuComposed() {
  return (
    <CommandMenu hotkey="j">
      <CommandMenuTrigger label="Search writing…" className="w-72" />
      <CommandMenuContent
        label="Search writing"
        placeholder="Search posts by title or topic…"
        empty={(query) => (
          <>
            <SearchX aria-hidden className="mb-1 size-5 text-muted-foreground" />
            <span className="font-medium">No posts about “{query}” yet</span>
            <span className="text-muted-foreground">Try “motion” or “tokens”.</span>
          </>
        )}
      >
        <CommandMenuGroup heading="Writing">
          {posts.map((post) => (
            <CommandMenuItem key={post.slug} value={post.title} keywords={post.tags} href={`#${post.slug}`} icon={<PenLine />}>
              {post.title}
              <span className="ml-2 font-mono text-xs text-muted-foreground tabular-nums max-sm:hidden">{post.readingTime}</span>
            </CommandMenuItem>
          ))}
        </CommandMenuGroup>
      </CommandMenuContent>
    </CommandMenu>
  )
}
```

## API Reference

### CommandMenu

Root: owns the open state and the ⌘K / Ctrl K hotkey. Pass `groups` for a ready-made menu,
or compose `<CommandMenuContent>` yourself. Put one or more `<CommandMenuTrigger>` inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `groups` | `CommandMenuGroupData[]` | — | Data-driven content. Omit and render `<CommandMenuContent>` yourself for full control. |
| `open` | `boolean` | — | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | — | Called when the menu opens or closes (trigger, hotkey, Esc, selecting an item). |
| `hotkey` | `string \| false` | `"k"` | Key that toggles the menu together with ⌘ / Ctrl. Ignored while the visitor is typing in another text field. `false` disables the shortcut. |
| `onNavigate` | `(href: string) => void` | — | Handle `href` items yourself (e.g. `router.push`). Defaults to `window.location`, a new tab for external URLs, and for same-page `#id` links a scroll to the element that moves focus there. |
| `placeholder` | `string` | — | Search placeholder (data-driven mode). |
| `children` | `React.ReactNode` | — | Triggers and/or a custom `<CommandMenuContent>`. |

### CommandMenuKbd

Deprecated alias of `Kbd`, kept for one release: use `Kbd` (one key) or `KbdShortcut` (a combination) from `kbd`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | — | `sm` for hints inside buttons, menus and dense text, `md` for running text, `lg` for a standalone "press this" prompt. |

Other props are forwarded to the root element.

### CommandMenuTrigger

Opens the menu. `variant="search"` looks like a search field with the shortcut hint;
`variant="icon"` is a compact icon button for phones. Pass `children` to render your own content. Hidden in print, where it can't be used.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"search" \| "icon"` | `"search"` | `search`: a field-like button with a label and the ⌘K hint, for wide headers. `icon`: a compact magnifier button for mobile or tight headers. |
| `label` | `string` | `"Search or jump to…"` | Label for the search variant (and accessible name for the icon variant). |

Also accepts every `button` prop.

### CommandMenuContent

The dialog: search field, results and the hint footer. Put `<CommandMenuGroup>`s and
`<CommandMenuItem>`s inside. The query resets every time the menu opens. On phones it is a
sheet pinned near the top, clear of the on-screen keyboard; results use the rest of the height.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholder` | `string` | `"Search or jump to…"` | Search field placeholder. |
| `label` | `string` | `"Command menu"` | Accessible name of the dialog. |
| `listLabel` | `string` | `"Results"` | Accessible name of the results list. |
| `closeLabel` | `string` | `"Close"` | Accessible name of the close button. |
| `resultsLabel` | `(count: number) => string` | `defaultResultsLabel` | What screen readers hear once typing pauses: "3 results", "1 result" or "No results" by default. |
| `empty` | `React.ReactNode \| ((query: string) => React.ReactNode)` | — | Shown when nothing matches. Receives the current query. |
| `footer` | `boolean \| React.ReactNode` | `true` | Show the ↑↓ / Enter / Esc hint row (hidden on small screens either way). |
| `commandProps` | `Omit<React.ComponentProps<typeof CommandPrimitive>, "children">` | — | Props for the underlying cmdk `Command` (e.g. your own `filter`, `shouldFilter` for async results). |

Also accepts every `Dialog.Content` prop.

### CommandMenuGroup

A labelled set of items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `string` | — | Label shown above the group's items. Hidden with the group when none of them match. |

Also accepts every `Command.Group` prop.

### CommandMenuItem

One result. Selecting it (click or ↵) runs `onSelect`, closes the menu and follows `href`. A same-page `#id` scrolls to that element and moves keyboard focus to it once the menu has closed.
Set `value` to a unique search string when `children` isn't plain text; add `keywords` for extra terms.
Long text is cut to one line; plain-text labels show in full on hover.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `React.ReactNode` | — | Leading icon: a lucide icon, `<BrandIcon>` or a small thumbnail such as `<GenerativeArt>`. |
| `href` | `string` | — | Navigate here on select (through `onNavigate`). External URLs open in a new tab. |
| `onSelect` | `() => void` | — | Run an action on select. |
| `shortcut` | `string[]` | — | Key hint to display, e.g. `["mod", "c"]` (⌘ C on Apple devices, Ctrl C elsewhere; see `KbdShortcut`). Display only: bind the keys yourself if needed. |
| `keepOpen` | `boolean` | `false` | Keep the menu open after selecting. |

Also accepts every `Command.Item` prop.

### CommandMenuSeparator

A hairline between groups.

Also accepts every `Command.Separator` prop.

### CommandMenuFooter

The keyboard-hint row under the results (hidden on small screens). Rendered by default;
pass your own as `<CommandMenuContent footer={<CommandMenuFooter>…</CommandMenuFooter>}>`.

Also accepts every `div` prop.

### type CommandMenuGroupData

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` (required) | `string` | — | Group label shown above its items. |
| `items` (required) | `CommandMenuItemData[]` | — |  |

### type CommandMenuItemData

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | — | Visible text; also the primary search value. Must be unique within the menu. |
| `icon` | `React.ReactNode` | — | Leading icon: a lucide icon, `<BrandIcon>` or a small thumbnail such as `<GenerativeArt>`. |
| `href` | `string` | — | Navigate here on select. External URLs open in a new tab. |
| `onSelect` | `() => void` | — | Run an action on select. |
| `shortcut` | `string[]` | — | Key hint to display, e.g. `["mod", "c"]` (⌘ C on Apple devices, Ctrl C elsewhere; see `KbdShortcut`). Display only: bind the keys yourself if needed. |
| `keywords` | `string[]` | — | Extra search terms. |
| `disabled` | `boolean` | — | Show the item but make it unselectable. |

## Used in templates

- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)
- [Not Found](https://www.parthjadhav.com/products/portfolio-kit/templates/not-found.md)



---

# Contact Bar

> A slim bar pinned to the bottom of the screen on phones that keeps “Email me” and “Book a call” one tap away once the hero has scrolled past, without covering the end of the page.

Category: Contact · Registry item: `@portfolio-kit/contact-bar` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/contact-bar) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/contact-bar.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/contact-bar
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/contact-bar.tsx` and the kit items it uses: `use-composed-refs`, `use-copy-to-clipboard`, `use-isomorphic-layout-effect`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  ContactBar,
  ContactBarAction,
  ContactBarCopyEmail,
} from "@/components/portfolio/contact-bar"

<ContactBar showAfter="#hero" hideNear="#contact" dismissible storageKey="contact-bar">
  <ContactBarCopyEmail email="hello@example.com" />
  <ContactBarAction href="https://cal.com/example" variant="primary">Book a call</ContactBarAction>
</ContactBar>
```

## Examples

### Demo

A floating contact pill that appears once the hero's own buttons scroll away and steps aside when the contact section arrives.

```tsx
import { CalendarDays } from "lucide-react"

import { ContactBar, ContactBarAction, ContactBarCopyEmail } from "@/components/portfolio/contact-bar"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { typography } from "@/lib/typography"

const projects = [
  { slug: "lumen", title: "Lumen", meta: "2025 · Design system", art: "interface" },
  { slug: "tidewater", title: "Tidewater", meta: "2025 · Grid monitoring", art: "interface" },
  { slug: "fieldnote", title: "Fieldnote", meta: "2024 · Identity and site", art: "bauhaus" },
] as const

export default function ContactBarDemo() {
  return (
    <>
      <main className="mx-auto flex max-w-2xl flex-col gap-16 px-5 py-16 sm:px-6 md:py-20">
        <header id="hero" className="flex flex-col gap-5">
          <p className={typography.eyebrow}>Product designer · Lisbon</p>
          <h1 className={typography.title}>I design calm tools for complicated work.</h1>
          <p className={typography.lead}>
            Scroll past these buttons and a contact bar takes over, so getting in touch is never more than a tap away.
          </p>
          <div className="flex flex-wrap gap-3">
            <a
              href="mailto:hello@example.com"
              className="inline-flex h-11 items-center rounded-pill bg-primary px-5 text-sm font-medium text-primary-foreground outline-none hover:bg-primary/90 focus-visible:ring-[3px] focus-visible:ring-ring/50"
            >
              Email me
            </a>
            <a
              href="#work"
              className="inline-flex h-11 items-center rounded-pill border px-5 text-sm font-medium outline-none hover:border-border-hover focus-visible:ring-[3px] focus-visible:ring-ring/50"
            >
              See work
            </a>
          </div>
        </header>
        <ul role="list" id="work" className="flex flex-col gap-12">
          {projects.map((project) => (
            <li key={project.slug} className="flex flex-col gap-3">
              <div className="aspect-[16/10] overflow-hidden rounded-2xl border bg-muted">
                <GenerativeArt seed={`contact-bar-${project.slug}`} variant={project.art} />
              </div>
              <p className={`${typography.meta} mt-2`}>{project.meta}</p>
              <h2 className={typography.heading}>{project.title}</h2>
            </li>
          ))}
        </ul>
        <section id="contact" aria-labelledby="contact-title" className="flex flex-col gap-4 border-t pt-12">
          <h2 id="contact-title" className={typography.title}>
            Let&apos;s talk.
          </h2>
          <p className={typography.lead}>
            The bar has stepped aside: this section already says how to reach me. Write to{" "}
            <a
              href="mailto:hello@example.com"
              className="text-foreground underline decoration-foreground/30 underline-offset-[0.2em] hover:text-highlight-ink"
            >
              hello@example.com
            </a>
            .
          </p>
        </section>
      </main>
      <ContactBar variant="floating" hideFrom={null} showAfter="#hero" hideNear="#contact">
        <ContactBarCopyEmail email="hello@example.com" />
        <ContactBarAction href="#book" variant="primary" icon={<CalendarDays />}>
          Book a call
        </ContactBarAction>
      </ContactBar>
    </>
  )
}
```

### Mobile bar

Docked to the bottom edge on phones only, with email, a message link and a call button; it hides while you scroll down and can be closed. Switch the preview to Mobile to see it.

```tsx
import { Mail, MessageCircle, Phone } from "lucide-react"

import { ContactBar, ContactBarAction } from "@/components/portfolio/contact-bar"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { typography } from "@/lib/typography"

const services = [
  { title: "Brand identity", detail: "Logo, type and colour systems for small studios and new products." },
  { title: "Websites", detail: "Designed and built in-house, fast and easy for your team to edit." },
  { title: "Product design", detail: "From the first flows to a design system your engineers enjoy." },
  { title: "Art direction", detail: "Shoots, campaigns and launch films, from brief to final cut." },
] as const

export default function ContactBarMobileBar() {
  return (
    <>
      <main className="mx-auto flex max-w-2xl flex-col gap-14 px-5 py-16 sm:px-6 md:py-20">
        <header className="flex flex-col gap-5">
          <p className={typography.eyebrow}>Independent studio · Porto</p>
          <h1 className={typography.title}>Small studio, big attention to detail.</h1>
          <p className={typography.lead}>
            On a phone the bar sits at the bottom from the start. Scroll down and it gets out of the way; scroll up and
            it&apos;s back. From 768px up the header carries the contact link instead.
          </p>
        </header>
        <div className="aspect-[4/3] overflow-hidden rounded-2xl border bg-muted">
          <GenerativeArt seed="contact-bar-studio" variant="landscape" />
        </div>
        <ul role="list" className="flex flex-col">
          {services.map((service) => (
            <li key={service.title} className="flex flex-col gap-1.5 border-b py-5 md:py-6">
              <h2 className={typography.heading}>{service.title}</h2>
              <p className={typography.body}>{service.detail}</p>
            </li>
          ))}
        </ul>
        <p className={typography.body}>
          The last line of the page stays readable: the bar adds a spacer as tall as itself at the end of the page.
        </p>
      </main>
      <ContactBar hideOnScroll dismissible label="Contact the studio">
        <ContactBarAction href="mailto:studio@example.com" icon={<Mail />}>
          Email
        </ContactBarAction>
        <ContactBarAction href="https://example.com/message" target="_blank" rel="noreferrer" icon={<MessageCircle />}>
          Message
        </ContactBarAction>
        <ContactBarAction href="tel:+351200000000" variant="primary" icon={<Phone />} aria-label="Call the studio" />
      </ContactBar>
    </>
  )
}
```

## API Reference

### ContactBar

The bar: a `complementary` landmark fixed to the bottom of the viewport, with the actions in one
row. It's hidden (and out of the Tab order) until `showAfter` is passed, while `hideNear` is on
screen and, with `hideOnScroll`, while scrolling down. With reduced motion it fades instead of
sliding. While keyboard focus is inside, it stays on screen; closing it moves focus to `focusTarget`.
It pads for the notch and home indicator (`env(safe-area-inset-*)`, which needs
`viewport-fit=cover` in your viewport meta) and isn't printed.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"bar" \| "floating" \| null` | `"bar"` | `bar`: docked edge to edge, clear of the home indicator. `floating`: an inset pill above the bottom edge. |
| `hideFrom` | `"sm" \| "md" \| "lg" \| null` | `"md"` | Hide the bar from this breakpoint up (your header carries the contact link there). `null` shows it at every width. |
| `showAfter` | `string \| number` | — | When to appear: a CSS selector (the bar shows once that element, usually the hero with its own call to action, has scrolled out of view) or a scroll distance in px. Omit to show it at once. |
| `hideNear` | `string` | — | CSS selector of an element (usually the contact section) that hides the bar while it's on screen. |
| `hideOnScroll` | `boolean` | `false` | Slide away while scrolling down and come back on scroll up. |
| `dismissible` | `boolean` | `false` | Show a close button. |
| `storageKey` | `string` | — | Remember the dismissal in `localStorage` under this key so the bar stays closed on the next visit. If storage is blocked, the bar simply shows again next time. On server-rendered pages, add `createContactBarScript(storageKey)` to `<head>` so a dismissed bar doesn't show for a moment before the page hydrates. |
| `onDismiss` | `() => void` | — | Called after the close button is pressed. |
| `focusTarget` | `string \| null` | `"main"` | Where focus goes when the close button had it: a CSS selector (your `main`, or a skip-link target). It's focused without scrolling, made focusable for that moment if it isn't, so focus doesn't drop to the page when the bar disappears. `null` never moves focus. |
| `dismissLabel` | `string` | `"Hide contact bar"` | Accessible name of the close button. |
| `label` | `string` | `"Contact"` | Accessible name of the `complementary` landmark. |
| `spacer` | `boolean` | `true` | Render an in-flow spacer as tall as the bar, so the last content on the page can scroll clear of it. Render `ContactBar` at the end of the page (after the footer) for this to work; turn it off if your layout already leaves room. |

Also accepts every `aside` prop.

### ContactBarAction

One action: a link (`mailto:`, `tel:`, a booking page, a chat link). Text actions share the row by
their length and truncate only when it's full; icon-only actions stay 44px square. Text links that
open a new tab show ↗, and every new-tab link says so to screen readers (`newTabLabel`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"primary" \| "secondary" \| null` | `"bar"` | `primary` fills it with the theme's primary colour; use it for the one action you most want taken. |
| `icon` | `React.ReactNode` | — | A lucide icon or `<BrandIcon>` before the label. Pass only an icon (and an `aria-label`) for a square button. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader note on links with `target="_blank"`. |

Also accepts every `a` prop.

### ContactBarCopyEmail

A button that copies your email address, then shows “Copied” for two seconds and announces it
politely. If the browser refuses to copy, a note above the bar shows `failedLabel` and the address,
already selected, for four seconds. Pair it with a `mailto:` action for people whose phone has a
mail app set up.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `email` (required) | `string` | — | The address to copy. |
| `children` | `React.ReactNode` | `"Copy email"` | Button text. The address itself is announced to screen readers. |
| `copiedLabel` | `string` | `"Copied"` | Text shown briefly after copying (also announced to screen readers). |
| `failedLabel` | `string` | `"Couldn’t copy — select the text"` | Shown above the bar, with the address ready to select, when the browser refuses to copy (also announced). |
| `variant` | `"primary" \| "secondary" \| null` | `"bar"` | `primary` fills it with the theme's primary colour. |

Also accepts every `button` prop.



---

# Contact CTA

> Closing section of a portfolio with a large invitation, availability, a copy-email button and actions. Centered, split, or under a scrolling “Let's talk” line.

Category: Contact · Registry item: `@portfolio-kit/contact-cta` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/contact-cta) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/contact-cta.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/contact-cta
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/contact-cta.tsx` and the kit items it uses: `availability-badge`, `marquee`, `section`, `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import { CopyEmail } from "@/components/portfolio/copy-email"
import {
  SocialLink,
  SocialLinks,
} from "@/components/portfolio/social-links"
import {
  ContactCta,
  ContactCtaActions,
  ContactCtaAvailability,
  ContactCtaDescription,
  ContactCtaTitle,
} from "@/components/portfolio/contact-cta"

<ContactCta id="contact">
  <ContactCtaAvailability detail="from November" />
  <ContactCtaTitle>
    Have a project in <em>mind?</em>
  </ContactCtaTitle>
  <ContactCtaDescription>I take on a few well-scoped projects each quarter.</ContactCtaDescription>
  <ContactCtaActions>
    <CopyEmail email="hello@example.com" variant="large" mailto />
    <SocialLinks>
      <SocialLink href="https://github.com/example" />
      <SocialLink href="https://www.linkedin.com/in/example" />
    </SocialLinks>
  </ContactCtaActions>
</ContactCta>
```

## Examples

### Demo

The closing section of a portfolio: availability, a large invitation, a copy-email button and the next steps.

```tsx
import { ArrowRight, CalendarDays } from "lucide-react"

import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import {
  ContactCta,
  ContactCtaActions,
  ContactCtaAvailability,
  ContactCtaDescription,
  ContactCtaRow,
  ContactCtaTitle,
} from "@/components/portfolio/contact-cta"
import { CopyEmail } from "@/components/portfolio/copy-email"
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"

export default function ContactCtaDemo() {
  return (
    <ContactCta id="contact">
      <ContactCtaAvailability detail="from November" />
      <ContactCtaTitle>
        Have a project in <em>mind?</em>
      </ContactCtaTitle>
      <ContactCtaDescription>
        I take on a few well-scoped projects each quarter — product design, front-end builds and design systems. Tell me
        what you&apos;re making.
      </ContactCtaDescription>
      <ContactCtaActions>
        <CopyEmail email="hello@example.com" variant="large" mailto />
        <ContactCtaRow>
          <a href="#book" className={cn(buttonVariants({ size: "lg" }), "h-11 rounded-pill px-5")}>
            <CalendarDays aria-hidden />
            Book an intro call
          </a>
          <a href="#work" className={cn(buttonVariants({ size: "lg", variant: "ghost" }), "group h-11 rounded-pill px-4")}>
            See selected work
            <ArrowRight aria-hidden className="transition-transform duration-300 ease-smooth group-hover:translate-x-0.5" />
          </a>
        </ContactCtaRow>
        <SocialLinks>
          <SocialLink href="https://github.com/example" />
          <SocialLink href="https://x.com/example" />
          <SocialLink href="https://www.linkedin.com/in/example" />
          <SocialLink href="https://dribbble.com/example" />
        </SocialLinks>
      </ContactCtaActions>
    </ContactCta>
  )
}
```

### Split

Text on the left, actions on the right. A left-aligned close that suits editorial layouts.

```tsx
import { CalendarDays } from "lucide-react"

import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import {
  ContactCta,
  ContactCtaActions,
  ContactCtaAvailability,
  ContactCtaDescription,
  ContactCtaRow,
  ContactCtaTitle,
} from "@/components/portfolio/contact-cta"
import { CopyEmail } from "@/components/portfolio/copy-email"
import { ResumeLink } from "@/components/portfolio/resume-link"
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"

export default function ContactCtaSplit() {
  return (
    <ContactCta variant="split">
      <ContactCtaAvailability status="limited" detail="one slot in Q1" />
      <ContactCtaTitle>
        Let&apos;s make something <em>calm.</em>
      </ContactCtaTitle>
      <ContactCtaDescription>
        Product design, front-end builds and design systems for teams who care about the details. I reply within two
        working days.
      </ContactCtaDescription>
      <ContactCtaActions>
        <CopyEmail email="hello@example.com" mailto />
        <ContactCtaRow>
          <a href="#book" className={cn(buttonVariants({ size: "lg" }), "h-11 rounded-pill px-5")}>
            <CalendarDays aria-hidden />
            Book a call
          </a>
          <ResumeLink href="/files/cv.pdf" fileName="noa-vale-cv.pdf" meta="PDF" />
        </ContactCtaRow>
        <SocialLinks variant="text">
          <SocialLink href="https://github.com/example" />
          <SocialLink href="https://www.linkedin.com/in/example" />
          <SocialLink href="https://dribbble.com/example" />
        </SocialLinks>
      </ContactCtaActions>
    </ContactCta>
  )
}
```

### Marquee

A large scrolling “Let's talk” line opens the section and works as a mailto link.

```tsx
import {
  ContactCta,
  ContactCtaActions,
  ContactCtaAvailability,
  ContactCtaDescription,
  ContactCtaTitle,
} from "@/components/portfolio/contact-cta"
import { CopyEmail } from "@/components/portfolio/copy-email"
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"

export default function ContactCtaMarqueeLine() {
  return (
    <ContactCta variant="marquee" marquee="Let's talk" marqueeHref="mailto:hello@example.com">
      <ContactCtaAvailability />
      <ContactCtaTitle>Got an idea that deserves a great interface?</ContactCtaTitle>
      <ContactCtaDescription>
        Send a few lines about the project, timeline and team. No brief required — a rough idea is a fine start.
      </ContactCtaDescription>
      <ContactCtaActions>
        <CopyEmail email="hello@example.com" mailto />
        <SocialLinks variant="pill">
          <SocialLink href="https://github.com/example" />
          <SocialLink href="https://www.linkedin.com/in/example" />
        </SocialLinks>
      </ContactCtaActions>
    </ContactCta>
  )
}
```

## API Reference

### ContactCta

The section itself. `centered` stacks everything in the middle; `split` puts the words left and
`<ContactCtaActions>` right; `marquee` adds a full-bleed "Let's talk" ticker above a split layout.
Like `Section`, it is labelled by its `ContactCtaTitle` (a named region, for a page-level closing
section); your own `aria-label` or `aria-labelledby` wins.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"centered" \| "split" \| "marquee" \| null` | `"centered"` | `centered`: everything stacked in the middle. `split`: words left, actions right. `marquee`: a giant "Let's talk" ticker above a split layout. |
| `marquee` | `React.ReactNode` | `"Let's talk"` | Text of the giant scrolling line (`marquee` variant only). |
| `marqueeHref` | `string` | — | Makes the marquee line a link, e.g. `mailto:hello@example.com` or `#contact` (`marquee` variant only). |
| `marqueeLabel` | `string` | — | Accessible name of the marquee link when `marquee` isn't plain text (`marquee` variant only). |
| `pauseLabel` | `string` | — | Accessible name of the marquee's pause button (`marquee` variant only). |
| `glow` | `boolean` | `false` | A faint wash of the highlight color rising from the bottom edge. Off by default. |
| `size` | `React.ComponentProps<typeof Container>["size"]` | — | Container width for the content. |

Also accepts every `section` prop.

### ContactCtaMarquee

Full-bleed, display-size ticker with a pause button below it. Rendered automatically by the
`marquee` variant; use it directly for custom layouts. Under reduced motion and in print the line
stands still, once, and wraps instead of running off the edge.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `React.ReactNode` | `"Let's talk"` | The repeated line. |
| `href` | `string` | — | Makes the whole line one link (e.g. `mailto:`). It pauses on hover and the separator arrow turns to point at it. |
| `duration` | `number` | `28` | Seconds per loop. Lower is faster. |
| `separator` | `React.ReactNode` | — | Glyph between repeats. Defaults to an arrow when the line is a link, otherwise a star. |
| `label` | `string` | — | Accessible name of the link. Defaults to the line when it's plain text, otherwise "Get in touch". |
| `pauseLabel` | `string` | `"Pause scrolling text"` | Accessible name of the pause button, which stops the loop (WCAG 2.2.2). |

Also accepts every `div` prop.

### ContactCtaTitle

Display-size heading. Wrap a word in `<em>` to tint it with the highlight color. Also names the section.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h1" \| "h2" \| "h3"` | `"h2"` | Heading level. |

Also accepts every `h2` prop.

### ContactCtaDescription

Lead paragraph under the title, e.g. what you take on and how fast you reply.

Also accepts every `p` prop.

### ContactCtaActions

Stack of actions, typically `<CopyEmail variant="large" />`, a button row and `<SocialLinks />`.

Also accepts every `div` prop.

### ContactCtaRow

A row inside the actions stack (buttons, socials).

Also accepts every `div` prop.

### ContactCtaAvailability

An `<AvailabilityBadge>` sized for this section.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | Turn the badge into a link, e.g. to your contact section or booking page. It gets a focus ring and the kit's hover; external URLs open in a new tab and say so to screen readers. |
| `variant` | `"pill" \| "soft" \| "plain"` | — | `pill`: bordered and frosted, for heroes over images or color. `soft`: a muted fill without border. `plain`: dot and text only, for inline use. |
| `ref` | `React.Ref<HTMLElement>` | — | The root element: the `<span>`, or the `<a>` when you pass `href`. |
| `status` | `"available" \| "limited" \| "unavailable"` | — | Your booking state. Sets the dot color and the default label ("Available for work", "Limited availability", "Not taking new projects"). |
| `pulse` | `boolean` | — | Pulse the dot twice, then rest (never when `unavailable`). Off for reduced motion. |
| `newTabLabel` | `string` | — | Screen-reader text added when `href` opens in a new tab. Translate it here. |
| `detail` | `React.ReactNode` | — | Secondary text, e.g. a date. Rendered muted after the label. |
| `truncate` | `boolean` | — | Keep the badge on one line and cut long text with an ellipsis. By default the text wraps when space runs out, so nothing is ever clipped. |

Also accepts every `AvailabilityBadge` prop.

## Used in templates

- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Contact Form

> Project inquiry form with name, email, company, budget and project-type chips and a message with a character count. Includes inline validation and sending, success and error states.

Category: Contact · Registry item: `@portfolio-kit/contact-form` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/contact-form) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/contact-form.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/contact-form
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/contact-form.tsx` and the kit items it uses: `typography`, `use-composed-refs`.

npm dependencies: `lucide-react`.

shadcn/ui primitives: `button`, `input`, `label`, `textarea`.

## Usage

```tsx
import { ContactForm } from "@/components/portfolio/contact-form"

<ContactForm
  onSubmit={async (data) => {
    const response = await fetch("/api/contact", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data)
    })
    if (!response.ok) throw new Error("Message could not be sent.")
  }}
  fallbackEmail="hello@example.com"
/>
```

## Examples

### Demo

A project inquiry form with inline validation, project-type and budget chips, and loading, success and error states handled for you.

```tsx
import { ContactForm, type ContactFormData } from "@/components/portfolio/contact-form"

async function sendInquiry(data: ContactFormData) {
  // Replace with your endpoint (Formspree, a server action, an API route…). Throw to show the error state.
  await new Promise((resolve) => setTimeout(resolve, 800))
  console.info("New inquiry", data)
}

export default function ContactFormDemo() {
  return (
    <div className="mx-auto w-full max-w-2xl rounded-2xl border bg-card p-5 text-card-foreground shadow-card md:p-8">
      <ContactForm onSubmit={sendInquiry} fallbackEmail="hello@example.com" />
    </div>
  )
}
```

### Minimal

Hide the company and budget fields and use your own reasons for reaching out, e.g. for a job search or a personal site.

```tsx
import { ContactForm, type ContactFormData } from "@/components/portfolio/contact-form"

async function sendMessage(data: ContactFormData) {
  await new Promise((resolve) => setTimeout(resolve, 800))
  console.info("New message", data)
}

export default function ContactFormMinimal() {
  return (
    <ContactForm
      onSubmit={sendMessage}
      hideCompany
      budgets={[]}
      projectTypes={["Freelance project", "Full-time role", "Speaking", "Just saying hi"]}
      maxLength={600}
      submitLabel="Send"
      note="Usually replies within a day."
      className="mx-auto w-full max-w-xl"
    />
  )
}
```

### In a Section

A contact page layout: intro, availability and direct email on the left, the form in a card on the right.

```tsx
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { ContactForm, type ContactFormData } from "@/components/portfolio/contact-form"
import { CopyEmail } from "@/components/portfolio/copy-email"
import {
  Section,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

async function sendInquiry(data: ContactFormData) {
  await new Promise((resolve) => setTimeout(resolve, 800))
  console.info("New inquiry", data)
}

export default function ContactFormInASection() {
  return (
    <Section id="contact">
      <div className="grid gap-12 lg:grid-cols-[minmax(0,2fr)_minmax(0,3fr)] lg:gap-16">
        <div className="flex flex-col gap-8">
          <SectionHeader>
            <SectionEyebrow>Contact</SectionEyebrow>
            <SectionTitle>Tell me about your project</SectionTitle>
            <SectionDescription>
              A few lines are plenty. I&apos;ll read it properly and reply within two working days.
            </SectionDescription>
          </SectionHeader>
          <AvailabilityBadge detail="from November" className="w-fit" />
          <div className="flex flex-col gap-3 border-t pt-6">
            <p className={typography.eyebrow}>Prefer email?</p>
            <CopyEmail email="hello@example.com" variant="ghost" mailto className="-ml-3" />
          </div>
        </div>
        <div className="rounded-2xl border bg-card p-5 text-card-foreground shadow-card md:p-8">
          <ContactForm onSubmit={sendInquiry} fallbackEmail="hello@example.com" />
        </div>
      </div>
    </Section>
  )
}
```

## API Reference

### ContactFormField

Label + control + error row. Use it to add your own fields in the same style.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `React.ReactNode` | — | Visible label. |
| `htmlFor` (required) | `string` | — | `id` of the control inside. Links the label, and the error (`<htmlFor>-error`) for `aria-describedby`. |
| `error` | `string` | — | Error message shown under the control. |
| `optional` | `boolean` | — | Adds a muted "(optional)" after the label. |
| `optionalLabel` | `React.ReactNode` | `"(optional)"` | Text of the optional marker, for translation. |
| `aside` | `React.ReactNode` | — | Right-aligned text under the control (e.g. a character count). |

Also accepts every `div` prop.

### ContactFormError

Inline error message with an alert icon.

Also accepts every `p` prop.

### ContactFormChips

A radio or checkbox group styled as pill chips (controlled).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Form field name of the inputs. |
| `legend` (required) | `React.ReactNode` | — | Group label. |
| `options` (required) | `string[]` | — | The choices, in order. |
| `type` (required) | `"radio" \| "checkbox"` | — | `radio`: pick one (click the picked chip again to clear it). `checkbox`: pick any. |
| `value` (required) | `string \| string[]` | — | The picked option (`""` for none). With `checkbox`, an array of picked options. |
| `onValueChange` (required) | `((value: string) => void) \| ((value: string[]) => void)` | — | Called with the new value when a chip is toggled. |
| `optional` | `boolean` | — | Adds a muted "(optional)" after the legend. |
| `optionalLabel` | `React.ReactNode` | `"(optional)"` | Text of the optional marker, for translation. |

Also accepts every `fieldset` prop.

### ContactForm

A complete inquiry form. Name, email and message are required (`required`, so screen readers
announce it); the other questions are marked optional. A field is checked when you leave it
with something typed, and every field on submit: errors appear under the fields, linked with
`aria-describedby` and `aria-invalid`, and focus moves to the first invalid one. While sending,
repeat submits are ignored; failures keep what was typed and show an alert; success swaps to a
focused thank-you panel. Wire `onSubmit` to your endpoint. Without JavaScript the browser posts
the form (native validation included) to `action`, so set `action` to an endpoint that accepts a
form post (e.g. a form service URL) if the page must work before scripts load.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSubmit` (required) | `(data: ContactFormData) => Promise<void> \| void` | — | Called with the validated, trimmed data. Return a promise to show the sending state; reject (throw) to show the error state. |
| `budgets` | `string[]` | `["Under $10k", "$10–25k", "$25–50k", "$50k+"]` | Budget chips (pick one, optional). Pass `[]` to hide the question. |
| `projectTypes` | `string[]` | `["Product design", "Website", "Design system", "Front-end build", "Something else"]` | Project-type chips (pick any, optional). Pass `[]` to hide the question. |
| `hideCompany` | `boolean` | `false` | Hide the optional company field. |
| `maxLength` | `number` | `1000` | Maximum message length; a counter under the message turns red at the limit. |
| `minMessageLength` | `number` | `20` | Minimum message length for it to be valid. |
| `submitLabel` | `React.ReactNode` | `"Send message"` | Submit button label. |
| `labels` | `Partial<ContactFormLabels>` | — | Translations of the built-in labels, placeholders and messages (any subset of `ContactFormLabels`). |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the thank-you heading, to fit your page outline. |
| `note` | `React.ReactNode` | `"I reply within two working days."` | Small print next to the submit button. Pass `null` to hide it. |
| `successTitle` | `React.ReactNode` | — | Heading after a successful send. Defaults to "Message sent — thank you, {first name}!" (`labels.successTitle`). |
| `successMessage` | `React.ReactNode` | `"Thanks for reaching out. I'll read it properly and get back to you within two working days."` | Paragraph under the success heading. |
| `fallbackEmail` | `string` | — | Offered as a fallback in the error message ("…or email me at …"). |
| `defaultValues` | `Partial<ContactFormData>` | — | Prefill fields, e.g. a project type chosen elsewhere on the page. |

Also accepts every `form` prop.

### type ContactFormData

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — |  |
| `email` (required) | `string` | — |  |
| `company` (required) | `string` | — |  |
| `budget` (required) | `string` | — |  |
| `projectTypes` (required) | `string[]` | — |  |
| `message` (required) | `string` | — |  |

### type ContactFormLabels

Every built-in string of `ContactForm`, for translation. Pass any subset to `labels`.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — |  |
| `namePlaceholder` (required) | `string` | — |  |
| `email` (required) | `string` | — |  |
| `emailPlaceholder` (required) | `string` | — |  |
| `company` (required) | `string` | — |  |
| `companyPlaceholder` (required) | `string` | — |  |
| `projectTypes` (required) | `string` | — | Legend of the project-type chips. |
| `budget` (required) | `string` | — | Legend of the budget chips. |
| `message` (required) | `string` | — |  |
| `messagePlaceholder` (required) | `string` | — |  |
| `optional` (required) | `string` | — | Muted marker after optional labels. Required fields carry no marker; the rest are marked optional. |
| `characters` (required) | `string` | — | Read after the character count by screen readers ("120 / 1000 characters"). |
| `nameMissing` (required) | `string` | — |  |
| `emailMissing` (required) | `string` | — |  |
| `emailInvalid` (required) | `string` | — |  |
| `messageTooShort` (required) | `(minLength: number) => string` | — |  |
| `sending` (required) | `string` | — | Submit button text while sending. |
| `sendingStatus` (required) | `string` | — | Announced to screen readers while sending. |
| `errorTitle` (required) | `string` | — |  |
| `errorRetry` (required) | `string` | — | Shown after `errorTitle` when there's no `fallbackEmail`. |
| `errorFallback` (required) | `string` | — | Shown before the `fallbackEmail` link. |
| `successTitle` (required) | `(firstName: string) => string` | — | Default success heading; gets the first name the visitor entered (may be empty). |
| `sendAnother` (required) | `string` | — |  |

## Used in templates

- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)



---

# Contribution Graph

> GitHub-style activity heatmap: weeks by weekdays in five levels of the theme's accent, with month and weekday labels, a legend and a total. Scrolls to the latest weeks on small screens.

Category: Content · Registry item: `@portfolio-kit/contribution-graph` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/contribution-graph) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/contribution-graph.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/contribution-graph
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/contribution-graph.tsx` and the kit items it uses: `format`, `typography`.

## Usage

```tsx
import {
  ContributionGraph,
} from "@/components/portfolio/contribution-graph"

<ContributionGraph
  label="Contributions in the last year"
  endDate="2025-10-14"
  data={[
    { date: "2025-10-12", count: 2 },
    { date: "2025-10-13", count: 7 },
    { date: "2025-10-14", count: 4 },
  ]}
/>
```

## Examples

### Demo

A year of activity. Pass one `{ date, count }` per day; levels, month labels and the total are computed for you.

```tsx
import { ContributionGraph, type ContributionDay } from "@/components/portfolio/contribution-graph"

/** Demo data: 52 weeks of daily counts from a seeded generator. Use your own (e.g. from the GitHub API) in practice. */
function sampleActivity(seed: number, end = "2026-02-28", days = 364): ContributionDay[] {
  let state = seed
  const random = () => (state = (state * 16807) % 2147483647) / 2147483647
  const last = Date.parse(`${end}T00:00:00Z`)
  let momentum = 0.5
  return Array.from({ length: days }, (_, i) => {
    const day = new Date(last - (days - 1 - i) * 86_400_000)
    const weekend = day.getUTCDay() === 0 || day.getUTCDay() === 6
    momentum = Math.min(1, Math.max(0, momentum + (random() - 0.5) * 0.3))
    const active = random() < (weekend ? 0.2 : 0.45 + momentum * 0.5)
    const count = active ? Math.ceil(random() ** 2 * (weekend ? 4 : 16) * (0.5 + momentum)) : 0
    return { date: day.toISOString().slice(0, 10), count }
  })
}

const activity = sampleActivity(7)

export default function ContributionGraphDemo() {
  return <ContributionGraph data={activity} label="Contributions in the last year" className="mx-auto py-6" />
}
```

### In a Card

An “open source” card for an about page. Set `--contribution-graph-bg` to the card color so the pinned weekday column blends in while scrolling.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { BrandIcon } from "@/components/portfolio/brand-icons"
import { ContributionGraph, type ContributionDay } from "@/components/portfolio/contribution-graph"
import { typography } from "@/lib/typography"

/** Demo data: 52 weeks of daily counts from a seeded generator. Use your own (e.g. from the GitHub API) in practice. */
function sampleActivity(seed: number, end = "2026-02-28", days = 364): ContributionDay[] {
  let state = seed
  const random = () => (state = (state * 16807) % 2147483647) / 2147483647
  const last = Date.parse(`${end}T00:00:00Z`)
  let momentum = 0.5
  return Array.from({ length: days }, (_, i) => {
    const day = new Date(last - (days - 1 - i) * 86_400_000)
    const weekend = day.getUTCDay() === 0 || day.getUTCDay() === 6
    momentum = Math.min(1, Math.max(0, momentum + (random() - 0.5) * 0.3))
    const active = random() < (weekend ? 0.2 : 0.45 + momentum * 0.5)
    const count = active ? Math.ceil(random() ** 2 * (weekend ? 4 : 16) * (0.5 + momentum)) : 0
    return { date: day.toISOString().slice(0, 10), count }
  })
}

const activity = sampleActivity(42)

const stats = [
  { label: "PRs merged", value: "184" },
  { label: "Best streak", value: "23 days" },
  { label: "Repositories", value: "31" },
]

export default function ContributionGraphInACard() {
  return (
    <div className="mx-auto flex w-fit max-w-full flex-col gap-6 rounded-2xl border bg-card p-5 text-card-foreground shadow-card [--contribution-graph-bg:var(--card)] md:p-6">
      <div className="flex flex-wrap items-center justify-between gap-x-6 gap-y-2">
        <div className="flex items-center gap-3">
          <BrandIcon name="github" className="size-5 shrink-0" />
          <h3 className={typography.heading}>Open source activity</h3>
        </div>
        <ArrowLink href="#github" tone="muted" className="text-sm">
          View profile
        </ArrowLink>
      </div>
      <ContributionGraph data={activity} label="GitHub contributions in the last year" />
      <dl className="grid grid-cols-3 gap-4 border-t pt-5">
        {stats.map((stat) => (
          <div key={stat.label} className="flex flex-col gap-1">
            <dt className={typography.meta}>{stat.label}</dt>
            <dd className="font-heading text-xl tabular-nums md:text-2xl">{stat.value}</dd>
          </div>
        ))}
      </dl>
    </div>
  )
}
```

### Habit Tracker

Any daily count works, not just commits. Words written over 13 weeks, starting on Mondays, with a custom cell label and caption.

```tsx
import { ContributionGraph, type ContributionDay } from "@/components/portfolio/contribution-graph"
import { formatDate } from "@/lib/format"
import { typography } from "@/lib/typography"

/** Demo data: words written per day over one quarter, from a seeded generator. */
function sampleWords(seed: number, end = "2026-03-01", days = 91): ContributionDay[] {
  let state = seed
  const random = () => (state = (state * 16807) % 2147483647) / 2147483647
  const last = Date.parse(`${end}T00:00:00Z`)
  return Array.from({ length: days }, (_, i) => {
    const day = new Date(last - (days - 1 - i) * 86_400_000)
    const wrote = random() < (day.getUTCDay() === 0 ? 0.3 : 0.7)
    return { date: day.toISOString().slice(0, 10), count: wrote ? Math.round((200 + random() * 1600) / 50) * 50 : 0 }
  })
}

const words = sampleWords(11)
const number = new Intl.NumberFormat("en-US")
const day = (date: Date) => formatDate(date, { weekday: "short", month: "short", day: "numeric" })

export default function ContributionGraphHabitTracker() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex flex-col gap-1">
        <p className={typography.eyebrow}>Writing streak</p>
        <h3 className={typography.heading}>Drafting the book, one morning at a time</h3>
      </div>
      <ContributionGraph
        data={words}
        weeks={13}
        weekStart={1}
        // A quarter is short: bigger cells give it presence.
        className="[--cell:16px]"
        label="Words written per day, last 13 weeks"
        cellLabel={(count, date) => (count ? `${number.format(count)} words on ${day(date)}` : `Rest day, ${day(date)}`)}
        caption={(total) => `${number.format(total)} words this quarter`}
      />
    </div>
  )
}
```

## API Reference

### ContributionGraph

The heatmap: weeks as columns, weekdays as rows, plus month/weekday labels and a footer with the
total and legend. It shrink-wraps its grid; when the container is narrower, the grid scrolls
(showing the latest weeks first) and the weekday column stays pinned. That column is painted
with `--contribution-graph-bg` (default: the page background), so set it to `var(--card)` inside
cards. Resize cells with `--cell` (e.g. `className="[--cell:8px]"`). Screen readers get a table: one row per
weekday, each day's count as its cell (`cellLabel`), and the total as the caption.

The graph is one Tab stop. Inside it the arrow keys move an outlined day (←/→ a week, ↑/↓ a day), Home/End go to
the first/last day of its week, Ctrl+Home/End to the first/last day shown and Page Up/Down a month; a line under
the grid shows that day's `cellLabel` and announces it politely. Mouse users keep the native tooltip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `ContributionDay[]` | — | One `{ date, count }` per day (`date` as `"2025-10-14"`). Missing days count as zero and duplicate dates are summed. Levels are the quartiles of the non-zero counts in range. |
| `endDate` | `string` | — | Last day shown (ISO date). Defaults to the latest date in `data`. Set it when `data` can be empty: the graph never reads the clock (server and browser would disagree), so with neither it shows an undated empty grid. |
| `weeks` | `number` | — | Number of weeks shown. Defaults to the range covered by `data`. |
| `weekStart` | `0 \| 1` | `0` | First row: `0` = Sunday (like GitHub), `1` = Monday. |
| `caption` | `(total: number, range: { start: Date; end: Date }) => React.ReactNode` | — | Custom caption. Receives the total count in range and the first/last day shown. |
| `cellLabel` | `(count: number, date: Date) => string` | `defaultCellLabel` | Custom cell label (tooltip + screen-reader text), e.g. `(n, date) => \`${n} words on …\``. |
| `showLegend` | `boolean` | `true` | Show the "Less ▢▢▢ More" legend under the graph. |
| `showTotal` | `boolean` | `true` | Show the total ("1,229 contributions in the last year") under the graph. |
| `label` | `string` | `"Contribution graph"` | Accessible name for the graph. |
| `lessLabel` | `string` | `"Less"` | Legend label before the swatches. |
| `moreLabel` | `string` | `"More"` | Legend label after the swatches. |
| `locale` | `string` | `"en-US"` | Locale for month and weekday names and the default total, e.g. `"de-DE"`. |

Also accepts every `div` prop.

### ContributionGraphLegend

The five level swatches between "Less" and "More". The graph renders one already (`showLegend`);
use this on its own to place the legend elsewhere. Inside a graph the swatches share its `--cell`
size; standalone they use the default sizes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `less` | `string` | `"Less"` | Label before the swatches. |
| `more` | `string` | `"More"` | Label after the swatches. |

Also accepts every `div` prop.

### type ContributionDay

One day of activity: an ISO date (`"2025-10-14"`) and how many things happened.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `date` (required) | `string` | — |  |
| `count` (required) | `number` | — |  |

## Used in templates

- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)



---

# Copy Email

> Your email as a button that copies it on click and briefly shows “Copied!”. Pill, ghost or display-size styles, with an optional mailto link.

Category: Contact · Registry item: `@portfolio-kit/copy-email` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/copy-email) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/copy-email.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/copy-email
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/copy-email.tsx` and the kit items it uses: `use-copy-to-clipboard`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  CopyEmail,
  CopyEmailButton,
  CopyEmailMailto,
} from "@/components/portfolio/copy-email"

<CopyEmail email="hello@example.com" copiedLabel="Copied!">
  <CopyEmailButton />
  <CopyEmailMailto subject="New project" />
</CopyEmail>
```

## Examples

### Demo

One click copies your address. The mailto link beside it opens a mail app instead.

```tsx
import { CopyEmail } from "@/components/portfolio/copy-email"

export default function CopyEmailDemo() {
  return (
    <div className="flex w-full max-w-md flex-col items-start gap-4">
      <p className="font-heading text-2xl leading-tight text-balance">Have a project in mind? Say hello.</p>
      <p className="text-sm text-pretty text-muted-foreground">A few lines about what you’re building is plenty. I reply within a working day.</p>
      <CopyEmail email="hello@example.com" mailto />
    </div>
  )
}
```

### Large

`variant="large"` sets the address at display size, with an underline that draws in on hover.

```tsx
import { CopyEmail } from "@/components/portfolio/copy-email"
import { typography } from "@/lib/typography"

export default function CopyEmailLarge() {
  return (
    <div className="mx-auto flex w-full max-w-5xl flex-col gap-6 py-10 md:py-16">
      <p className={typography.eyebrow}>Say hello</p>
      <CopyEmail email="hello@example.com" variant="large" mailto />
    </div>
  )
}
```

### Ghost

The borderless `ghost` style tucks into footers, headers and bylines without shouting.

```tsx
import { CopyEmail } from "@/components/portfolio/copy-email"
import { typography } from "@/lib/typography"

export default function CopyEmailGhost() {
  return (
    <footer className="mx-auto flex w-full max-w-5xl flex-col gap-4 border-t pt-6 sm:flex-row sm:items-center sm:justify-between">
      <p className={typography.meta}>© 2025 Noa Vale · Lisbon</p>
      <CopyEmail email="hello@example.com" variant="ghost" mailto className="-ml-3 sm:-mr-2.5 sm:ml-0" />
    </footer>
  )
}
```

### Custom Label

Compose the parts to change the wording: a short button label and a mailto link with a prefilled subject.

```tsx
import { CopyEmail, CopyEmailButton, CopyEmailMailto } from "@/components/portfolio/copy-email"

export default function CopyEmailCustomLabel() {
  return (
    <div className="flex w-full max-w-sm flex-col items-start gap-4 rounded-2xl border bg-card p-5 text-card-foreground shadow-card md:p-6">
      <p className="font-heading text-xl leading-snug text-balance">Working on something? I’d like to hear about it.</p>
      <CopyEmail email="hello@example.com" copiedLabel="Copied — talk soon!">
        <CopyEmailButton>Copy my email</CopyEmailButton>
        <CopyEmailMailto subject="Project inquiry">Write to me</CopyEmailMailto>
      </CopyEmail>
    </div>
  )
}
```

## API Reference

### CopyEmail

Root. Renders `<CopyEmailButton />` (and `<CopyEmailMailto />` when `mailto`) by default;
pass children to compose the parts yourself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `email` (required) | `string` | — | The address that gets copied (and used for the mailto link). |
| `variant` | `"pill" \| "ghost" \| "large" \| null` | `"pill"` | `pill`: bordered button with an icon chip. `ghost`: borderless, for footers and bylines. `large`: the address at display size, for the middle of a contact section. |
| `copiedLabel` | `string` | `"Copied!"` | Text that briefly replaces the label after copying (also announced to screen readers). |
| `failedLabel` | `string` | `"Couldn’t copy — select the text"` | Shown under the button, with the address ready to select, when the browser refuses to copy (also announced). |
| `label` | `string` | `"Copy email address"` | Start of the copy button's accessible name; the address follows it. |
| `mailtoLabel` | `string` | `"Open in mail app"` | Accessible name of the icon-only mailto link (pill and ghost) and the large style's link text. |
| `resetAfter` | `number` | `2000` | How long the copied state lasts, in ms. |
| `mailto` | `boolean` | `false` | Render a mailto link next to the button (only when no children are passed). |

Also accepts every `div` prop.

### CopyEmailButton

The copy button: icon plus the address (or your label), which morphs into the copied label on click. If the
browser refuses to copy, the root shows `failedLabel` and the address, selected, under the button. In print
only the address (or label) shows, without the icon or button chrome.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `React.ReactNode` | — | Replace the idle label (defaults to the email address). The address is still announced to screen readers. |

Also accepts every `button` prop.

### CopyEmailMailto

Secondary "open in mail app" link. Icon-only in pill/ghost styles (named by `mailtoLabel`), a text link in the large style. Hidden in print.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `subject` | `string` | — | Prefilled subject line. |

Also accepts every `a` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md)
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Credentials

> Education, certifications, courses and awards as rows with a kind icon, issuer, date and an optional verify link.

Category: About · Registry item: `@portfolio-kit/credentials` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/credentials) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/credentials.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/credentials
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/credentials.tsx` and the kit items it uses: `format`, `typography`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import {
  CredentialItem,
  CredentialList,
} from "@/components/portfolio/credentials"

<CredentialList>
  <CredentialItem kind="degree" heading="MSc Interaction Design" issuer="Northern School of Design" date="2014 — 2016" />
  <CredentialItem
    kind="certificate"
    heading="Certified Accessibility Specialist"
    issuer="Open Accessibility Council"
    date="2023-05"
    href="https://example.com/verify"
  />
</CredentialList>
```

## Examples

### Demo

Degrees, certificates, courses and awards in one list, each with an issuer, a date and an optional verify link.

```tsx
import { CredentialItem, CredentialList } from "@/components/portfolio/credentials"

export default function CredentialsDemo() {
  return (
    <CredentialList className="w-full max-w-2xl">
      <CredentialItem kind="degree" heading="MSc Interaction Design" issuer="Northern School of Design" date="2014 — 2016" />
      <CredentialItem
        kind="certificate"
        heading="Certified Accessibility Specialist"
        issuer="Open Accessibility Council"
        date="2023-05"
        href="#verify-a11y"
      />
      <CredentialItem
        kind="course"
        heading="Advanced Motion for Interfaces"
        issuer="Interface School"
        date="2022"
        href="#course-motion"
        hrefLabel="Course page"
      />
      <CredentialItem kind="award" heading="Site of the Day — Fieldnote" issuer="Web Craft Awards" date="2024-09" />
    </CredentialList>
  )
}
```

### With Notes

Add a short note under any credential (a thesis, honours, what a course covered) and rename the kind label, e.g. BSc or MSc.

```tsx
import { CredentialItem, CredentialList } from "@/components/portfolio/credentials"

export default function CredentialsWithNotes() {
  return (
    <CredentialList className="w-full max-w-2xl">
      <CredentialItem
        kind="degree"
        kindLabel="MSc"
        heading="Interaction Design"
        issuer="Northern School of Design"
        date="2014 — 2016"
      >
        Thesis on perceptual colour spaces for data visualisation. Graduated with distinction.
      </CredentialItem>
      <CredentialItem
        kind="degree"
        kindLabel="BSc"
        heading="Computer Science, minor in Visual Communication"
        issuer="University of the Coast"
        date="2010 — 2014"
      >
        Built the department&rsquo;s first accessible course catalogue as a final-year project.
      </CredentialItem>
      <CredentialItem
        kind="course"
        heading="Shader Fundamentals"
        issuer="Creative Code Collective"
        date="2025-03"
        href="#course-shaders"
        hrefLabel="Certificate"
      >
        Eight weeks of GLSL, noise and signed distance fields — mostly for fun.
      </CredentialItem>
    </CredentialList>
  )
}
```

### In a Section

A résumé-style section: the heading on the left, credentials on the right, stacking on mobile.

```tsx
import { CredentialItem, CredentialList } from "@/components/portfolio/credentials"
import {
  Section,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

export default function CredentialsInASection() {
  return (
    <Section spacing="sm">
      <div className="grid gap-10 md:grid-cols-[minmax(0,4fr)_minmax(0,8fr)] md:gap-16">
        <SectionHeader className="md:self-start">
          <SectionEyebrow index={4}>Credentials</SectionEyebrow>
          <SectionTitle className="md:text-4xl">Education &amp; awards</SectionTitle>
          <SectionDescription className="text-base md:text-base">
            Formal training, a few certificates worth keeping and some kind words from juries.
          </SectionDescription>
        </SectionHeader>
        <CredentialList>
          <CredentialItem kind="degree" kindLabel="MSc" heading="Interaction Design" issuer="Northern School of Design" date="2016" />
          <CredentialItem
            kind="certificate"
            heading="Certified Accessibility Specialist"
            issuer="Open Accessibility Council"
            date="2023-05"
            href="#verify-a11y"
          />
          <CredentialItem kind="award" heading="Site of the Day — Fieldnote" issuer="Web Craft Awards" date="2024-09" />
          <CredentialItem kind="award" kindLabel="Honorable mention" heading="Tidewater dashboard" issuer="Data Design Awards" date="2025" />
        </CredentialList>
      </div>
    </Section>
  )
}
```

## API Reference

### CredentialList

The list. Put `CredentialItem`s inside; rows are separated by hairlines.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading element for each credential's name. Pick the level below the section's heading. |

Also accepts every `ul` prop.

### CredentialItem

One credential row: kind icon, heading, issuer and kind label, then date and link. Children render as a short note.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `React.ReactNode` | — | Name of the degree, certificate, course or award. Rendered as the list's `headingLevel` (`<h3>` by default). Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `kind` | `"degree" \| "certificate" \| "course" \| "award"` | `"certificate"` | Picks the icon and the default label. |
| `kindLabel` | `string` | — | Override the kind label, e.g. "MSc" or "Honorable mention". |
| `icon` | `React.ReactNode` | — | Replace the kind icon (e.g. a lucide icon or the issuer's logo). |
| `issuer` | `React.ReactNode` | — | Who granted it: a school, company or jury. |
| `date` | `string` | — | `"2021"`, `"2021-06"` (shown as "Jun 2021"), a range like `"2014 — 2018"` or `"2023 — present"`, or any free text. Machine-readable parts become `<time>` elements. |
| `href` | `string` | — | Verification / certificate URL. Absolute URLs open in a new tab. |
| `hrefLabel` | `string` | `"Verify"` | Link text. Screen readers hear it followed by the heading, e.g. "Verify Certified Accessibility Specialist". |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added when `href` opens in a new tab. Translate it here. |
| `locale` | `string` | `"en-US"` | Locale used to format month dates. |

Also accepts every `li` prop.



---

# Credits List

> Colophon-style credits: roles paired with the people behind them (optionally linked), as ruled columns, centered film credits or one compact inline line.

Category: About · Registry item: `@portfolio-kit/credits-list` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/credits-list) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/credits-list.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/credits-list
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/credits-list.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  Credit,
  CreditsGroup,
  CreditsList,
} from "@/components/portfolio/credits-list"

<CreditsList>
  <CreditsGroup label="Design & code">
    <Credit>Mara Lindqvist</Credit>
  </CreditsGroup>
  <CreditsGroup label="Photography">
    <Credit href="https://example.com/theo" note="Portraits">
      Theo Okafor
    </Credit>
  </CreditsGroup>
</CreditsList>
```

## Examples

### Demo

A colophon for your site: who built it with you, the typefaces and tools, and the people you want to thank.

```tsx
import { Credit, CreditsGroup, CreditsList } from "@/components/portfolio/credits-list"

export default function CreditsListDemo() {
  return (
    <CreditsList className="mx-auto max-w-3xl">
      <CreditsGroup label="Design & code">
        <Credit>Mara Lindqvist</Credit>
      </CreditsGroup>
      <CreditsGroup label="Photography">
        <Credit href="https://example.com/theo-okafor" note="Portraits">
          Theo Okafor
        </Credit>
        <Credit href="https://example.com/studio-halden" note="Studio shots">
          Studio Halden
        </Credit>
      </CreditsGroup>
      <CreditsGroup label="Typefaces">
        <Credit note="Headings">Grotesk Neue</Credit>
        <Credit note="Body & code">Plex Sans &amp; Mono</Credit>
      </CreditsGroup>
      <CreditsGroup label="Mentors">
        <Credit href="https://example.com/june-arrow">June Arrow</Credit>
        <Credit href="https://example.com/sam-reyes">Sam Reyes</Credit>
      </CreditsGroup>
      <CreditsGroup label="Special thanks" columns={2}>
        <Credit>Ada Moreno</Credit>
        <Credit>Ines Park</Credit>
        <Credit>Kofi Mensah</Credit>
        <Credit>Lea Brandt</Credit>
        <Credit>Noor Haddad</Credit>
        <Credit>Everyone who filed an issue</Credit>
      </CreditsGroup>
    </CreditsList>
  )
}
```

### Centered

Film-credits layout for the end of a case study: roles right-aligned, names left-aligned, meeting at a center gutter.

```tsx
import { Credit, CreditsGroup, CreditsList } from "@/components/portfolio/credits-list"
import { typography } from "@/lib/typography"

export default function CreditsListCentered() {
  return (
    <div className="mx-auto flex max-w-2xl flex-col items-center gap-10 py-6 md:gap-12">
      <p className={typography.eyebrow}>Northwind rebrand — credits</p>
      <CreditsList variant="centered">
        <CreditsGroup label="Client">
          <Credit>Northwind Rail</Credit>
        </CreditsGroup>
        <CreditsGroup label="Creative direction">
          <Credit>Mara Lindqvist</Credit>
        </CreditsGroup>
        <CreditsGroup label="Design">
          <Credit>Ines Park</Credit>
          <Credit>Kofi Mensah</Credit>
        </CreditsGroup>
        <CreditsGroup label="Motion">
          <Credit href="https://example.com/lea-brandt">Lea Brandt</Credit>
        </CreditsGroup>
        <CreditsGroup label="Type design">
          <Credit href="https://example.com/foundry" note="custom cut">
            Foundry North
          </Credit>
        </CreditsGroup>
      </CreditsList>
    </div>
  )
}
```

### Inline

One compact, wrapping line for a footer or an about page's colophon.

```tsx
import { Credit, CreditsGroup, CreditsList } from "@/components/portfolio/credits-list"

export default function CreditsListInline() {
  return (
    <footer className="mx-auto flex max-w-3xl flex-col gap-3 border-t pt-6">
      <CreditsList variant="inline">
        <CreditsGroup label="Built with">
          <Credit href="https://example.com/react">React</Credit>
          <Credit href="https://example.com/tailwind">Tailwind</Credit>
        </CreditsGroup>
        <CreditsGroup label="Set in">
          <Credit>Grotesk Neue</Credit>
          <Credit>Plex Mono</Credit>
        </CreditsGroup>
        <CreditsGroup label="Photos">
          <Credit href="https://example.com/theo-okafor">Theo Okafor</Credit>
        </CreditsGroup>
        <CreditsGroup label="Thanks">
          <Credit>June Arrow</Credit>
          <Credit note="for the endless feedback">Sam Reyes</Credit>
        </CreditsGroup>
      </CreditsList>
    </footer>
  )
}
```

## API Reference

### CreditsList

The `<dl>` of `CreditsGroup`s. `columns` (default) is a ruled two-column table, roles on the left;
`centered` is film-credits style, roles and names meeting at a center gutter; `inline` runs every
group into one wrapping line for footers and colophons.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"columns" \| "centered" \| "inline"` | `"columns"` | `columns`: a ruled table, roles left and names right. `centered`: film-credits style around a center gutter. `inline`: one wrapping line, for footers. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added to credit links that open in a new tab. Translate it here; a `Credit` can override it. |

Also accepts every `dl` prop.

### CreditsGroup

One role and its people. Put `Credit`s inside; each renders a `<dd>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `React.ReactNode` | — | What these people did, e.g. "Design & code" or "Special thanks". Rendered as the `<dt>`. |
| `columns` | `1 \| 2` | `1` | Split long name lists (a "Thanks" group) into two columns. Only affects the `columns` variant. |

Also accepts every `div` prop.

### Credit

One person (or studio). `children` is the name.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | Their site or profile. External URLs open in a new tab, marked with ↗ and announced to screen readers. |
| `note` | `React.ReactNode` | — | Secondary detail after the name, e.g. a studio, "for the typeface" or "illustration". |
| `newTabLabel` | `string` | — | Screen-reader text added when `href` opens in a new tab. Defaults to the list's `newTabLabel`. |

Also accepts every `dd` prop.



---

# Custom Cursor

> A dot and trailing ring that follow the pointer, grow over links and buttons, and show a text label over elements with `data-cursor`. Page-wide or scoped to a container.

Category: Effects · Registry item: `@portfolio-kit/custom-cursor` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/custom-cursor) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/custom-cursor.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/custom-cursor
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/custom-cursor.tsx` and the kit items it uses: `use-composed-refs`, `use-fine-pointer`, `use-media-query`, `use-reduced-motion`.

## Usage

```tsx
import { CustomCursor } from "@/components/portfolio/custom-cursor"
```

## Examples

### Demo

Scope the cursor to a work grid: it grows over links and turns into a “View” pill over project covers tagged with `data-cursor`.

```tsx
import * as React from "react"

import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import { CustomCursor } from "@/components/portfolio/custom-cursor"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { typography } from "@/lib/typography"

const projects = [
  { slug: "lumen", title: "Lumen", year: 2025, art: "interface", cursor: "View" },
  { slug: "tidewater", title: "Tidewater", year: 2025, art: "interface", cursor: "View" },
  { slug: "fieldnote", title: "Fieldnote", year: 2024, art: "interface", cursor: "Case study" },
] as const

export default function CustomCursorDemo() {
  const scope = React.useRef<HTMLDivElement>(null)

  return (
    <div
      ref={scope}
      className="mx-auto flex max-w-5xl flex-col gap-8 rounded-2xl border bg-muted/40 p-5 md:gap-10 md:p-10"
    >
      <div className="flex flex-col gap-5 sm:flex-row sm:items-end sm:justify-between">
        <div className="flex flex-col gap-3">
          <p className={cn(typography.meta, "[@media(hover:none)]:hidden [@media(pointer:coarse)]:hidden motion-reduce:hidden")}>Move your pointer over the projects</p>
          <h2 className={typography.title}>Selected work</h2>
        </div>
        <a href="#archive" className={buttonVariants({ variant: "outline", className: "w-fit rounded-pill" })}>
          Full archive
        </a>
      </div>
      <ul role="list" className="grid gap-5 sm:grid-cols-3">
        {projects.map((project) => (
          <li key={project.slug}>
            <a
              href={`#${project.slug}`}
              data-cursor={project.cursor}
              className="group flex flex-col gap-3 rounded-xl outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
            >
              <span className="relative block aspect-[4/3] overflow-hidden rounded-xl border bg-muted">
                <GenerativeArt
                  seed={project.slug}
                  variant={project.art}
                  className="transition-transform duration-700 ease-smooth motion-reduce:transition-none [@media(hover:hover)]:group-hover:scale-[1.04]"
                />
              </span>
              <span className="flex items-baseline justify-between gap-3">
                <span className={typography.heading}>{project.title}</span>
                <span className={typography.meta}>{project.year}</span>
              </span>
            </a>
          </li>
        ))}
      </ul>
      <CustomCursor scope={scope} />
    </div>
  )
}
```

### Blend

Page-wide cursor with `blend` and `hideNativeCursor`: it inverts whatever sits underneath, so it stays visible over type and images alike.

```tsx
import { cn } from "@/lib/utils"
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { CustomCursor } from "@/components/portfolio/custom-cursor"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Section } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

const links = [
  { label: "Work", href: "#work" },
  { label: "About", href: "#about" },
  { label: "Contact", href: "#contact" },
]

export default function CustomCursorBlend() {
  return (
    <Section>
      <CustomCursor blend hideNativeCursor />
      <div className="grid items-center gap-10 md:grid-cols-[1.5fr_1fr] md:gap-16">
        <div className="flex flex-col gap-6">
          <p className={cn(typography.meta, "[@media(hover:none)]:hidden [@media(pointer:coarse)]:hidden motion-reduce:hidden")}>Move your pointer over the headline and the artwork</p>
          <h1 className={cn(typography.display, "lg:text-7xl")}>
            Make the interface feel <em>inevitable</em>.
          </h1>
          <nav aria-label="Primary">
            <ul role="list" className="flex flex-wrap gap-x-8 gap-y-3">
              {links.map((link) => (
                <li key={link.href}>
                  <ArrowLink href={link.href}>{link.label}</ArrowLink>
                </li>
              ))}
            </ul>
          </nav>
        </div>
        <div className="aspect-[4/5] overflow-hidden rounded-2xl border max-md:hidden">
          <GenerativeArt seed="inevitable" variant="portrait" />
        </div>
      </div>
    </Section>
  )
}
```

### Labels

Give each row its own verb with `data-cursor` (Read, Watch, Listen) so the cursor says what a click will do.

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"
import { CustomCursor } from "@/components/portfolio/custom-cursor"
import { typography } from "@/lib/typography"

const items = [
  { title: "Designing motion that respects attention", kind: "Essay", date: "2025-09-02", cursor: "Read" },
  { title: "Tokens are an API", kind: "Talk", date: "2025-06-18", cursor: "Watch" },
  { title: "Interfaces at walking pace", kind: "Podcast", date: "2025-03-04", cursor: "Listen" },
]

const formatDate = (iso: string) =>
  new Date(iso).toLocaleDateString("en-US", { month: "short", year: "numeric", timeZone: "UTC" })

export default function CustomCursorLabels() {
  const scope = React.useRef<HTMLDivElement>(null)

  return (
    <div ref={scope} className="mx-auto flex max-w-3xl flex-col gap-6">
      <p className={cn(typography.meta, "[@media(hover:none)]:hidden [@media(pointer:coarse)]:hidden motion-reduce:hidden")}>Hover a row to see its label</p>
      <ul role="list" className="border-t">
        {items.map((item) => (
          <li key={item.title} className="border-b">
            <a
              href="#writing"
              data-cursor={item.cursor}
              className="group flex flex-col gap-1 py-5 outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 sm:flex-row sm:items-baseline sm:justify-between sm:gap-6 md:py-6"
            >
              <span
                className={cn(
                  typography.heading,
                  "transition-colors duration-300 ease-smooth group-hover:text-highlight-ink"
                )}
              >
                {item.title}
              </span>
              <span className={cn(typography.meta, "flex shrink-0 gap-3")}>
                <span>{item.kind}</span>
                <time dateTime={item.date}>{formatDate(item.date)}</time>
              </span>
            </a>
          </li>
        ))}
      </ul>
      <CustomCursor scope={scope} />
    </div>
  )
}
```

## API Reference

### CustomCursor

Renders into `document.body` so transformed ancestors can't break `position: fixed`.
Label an element with `data-cursor="View"` to turn the ring into a pill with that text;
`data-cursor=""` just grows the ring.

Decorative: hidden from assistive technology and never catches the pointer. Renders nothing
on touch screens, with reduced motion and in forced-colors (high contrast) mode. It steps aside
over text fields and while the keyboard is in use, so it never sits on a caret or a focus ring.
The native cursor is always the fallback, so never put essential information in a label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scope` | `React.RefObject<HTMLElement \| null>` | — | Only follow the pointer inside this element. Omit to use the whole page. |
| `hideNativeCursor` | `boolean` | `false` | Hide the system cursor while the custom one is showing (inside `scope`, or on the whole page). It comes back over text fields, while the keyboard is in use and whenever the custom cursor is hidden. |
| `blend` | `boolean` | `false` | Invert colors against whatever is underneath with `mix-blend-mode: difference`. |
| `targets` | `string` | `"a[href], button, [role=button], [data-cursor], input, textarea, select, label, summary"` | Elements that make the ring grow. `[data-cursor]` elements are always included. |
| `smoothing` | `number` | `0.2` | How quickly the ring catches up with the dot (0–1, per 60fps frame). Lower trails further behind; `1` sticks to the pointer. |

Also accepts every `div` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)



---

# Device Frame

> Browser, phone, laptop and window frames for screenshots, videos or artwork, drawn with theme tokens.

Category: Work · Registry item: `@portfolio-kit/device-frame` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/device-frame) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/device-frame.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/device-frame
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/device-frame.tsx`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import { DeviceFrame, deviceFrameVariants } from "@/components/portfolio/device-frame"
```

## Examples

### Demo

Present a screenshot in a browser window with a tab and address bar.

```tsx
import { DeviceFrame } from "@/components/portfolio/device-frame"
import { GenerativeArt } from "@/components/portfolio/generative-art"

export default function DeviceFrameDemo() {
  return (
    <DeviceFrame
      heading="Lumen — Components"
      url="https://lumen.example.com/components/button"
      className="mx-auto max-w-3xl"
    >
      <GenerativeArt seed="lumen-home" variant="interface" hue={40} label="Screenshot of the Lumen component explorer" />
    </DeviceFrame>
  )
}
```

### Phone

A phone with a dynamic island for mobile apps and responsive screenshots. The bezel turns square in square themes.

```tsx
import { DeviceFrame } from "@/components/portfolio/device-frame"
import { GenerativeArt } from "@/components/portfolio/generative-art"

export default function DeviceFramePhone() {
  return (
    <DeviceFrame variant="phone" className="max-w-60">
      <GenerativeArt seed="tidewater-mobile" variant="interface" hue={195} label="Tidewater mobile app" />
    </DeviceFrame>
  )
}
```

### Laptop

A laptop lid and base for marketing sites and desktop apps, a softer look than a browser window.

```tsx
import { DeviceFrame } from "@/components/portfolio/device-frame"
import { GenerativeArt } from "@/components/portfolio/generative-art"

export default function DeviceFrameLaptop() {
  return (
    <DeviceFrame variant="laptop" className="mx-auto max-w-3xl">
      <GenerativeArt seed="fieldnote" variant="interface" label="Fieldnote marketing site" />
    </DeviceFrame>
  )
}
```

### Window

A titled app window holding any markup. Here a code sample sets the height with `ratio="auto"`.

```tsx
import { DeviceFrame } from "@/components/portfolio/device-frame"

const code = `import { track } from "@orbit/analytics"

track("checkout_completed", {
  plan: "team",
  seats: 12,
})`

export default function DeviceFrameWindow() {
  return (
    <DeviceFrame variant="window" heading="checkout.ts — Orbit" ratio="auto" screenClassName="bg-card" className="mx-auto max-w-lg">
      <pre className="overflow-x-auto p-4 font-mono text-xs leading-relaxed text-foreground md:p-5 md:text-sm">
        <code>{code}</code>
      </pre>
    </DeviceFrame>
  )
}
```

### Desktop + Mobile

Overlap a browser and a phone to show a responsive build in one hero image.

```tsx
import { DeviceFrame } from "@/components/portfolio/device-frame"
import { GenerativeArt } from "@/components/portfolio/generative-art"

export default function DeviceFrameComposition() {
  return (
    <div className="mx-auto w-full max-w-4xl pr-4 pb-12 md:pr-10 md:pb-16">
      <div className="relative">
        <DeviceFrame heading="Kiln Ceramics" url="https://kiln.example.com">
          <GenerativeArt seed="kiln-home" variant="interface" hue={30} label="Kiln Ceramics storefront" />
        </DeviceFrame>
        <DeviceFrame
          variant="phone"
          className="absolute -right-4 -bottom-12 w-[28%] max-w-52 min-w-24 md:-right-10 md:-bottom-16"
        >
          <GenerativeArt seed="kiln-home" variant="interface" hue={30} label="Kiln Ceramics storefront on mobile" />
        </DeviceFrame>
      </div>
    </div>
  )
}
```

## API Reference

### DeviceFrame

Chrome around a screenshot, video or any markup. Put one `<img>`, `<video>` or `GenerativeArt` inside and it
fills the screen (`object-cover`, top-aligned); with `ratio="auto"` the content sets the height.
The chrome is built from theme tokens, so it follows radius, borders and shadows of the active theme.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"browser" \| "phone" \| "laptop" \| "window"` | `"browser"` | `browser` (address bar, optional tab), `phone` (dynamic island), `laptop` (lid + base) or `window` (title bar). |
| `url` | `string` | — | Address shown in the browser URL pill (protocol is stripped). |
| `heading` | `string` | — | Tab title (browser) or window title (window). |
| `title` | `string` | — | Deprecated alias of `heading`. |
| `ratio` | `"auto" \| "video" \| "desktop" \| "photo" \| "square" \| "phone"` | — | Screen aspect ratio: `video` 16:9, `desktop` 16:10, `photo` 4:3, `square`, `phone` 9:19.5, or `auto` to let the content set the height. Defaults to `phone` for the phone and `desktop` for the others. |
| `screenClassName` | `string` | — | Class for the screen area that wraps `children`. |

Also accepts every `div` prop.

## Used in templates

- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)



---

# Dot Map

> A dotted world map with pins for where you’re based, your clients or your travels, plus optional pulsing and connecting arcs. Pure SVG, no map library.

Category: About · Registry item: `@portfolio-kit/dot-map` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/dot-map) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/dot-map.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/dot-map
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/dot-map.tsx` and the kit items it uses: `use-composed-refs`, `use-in-view`, `use-isomorphic-layout-effect`, `use-reduced-motion`.

## Usage

```tsx
import {
  DotMap,
  DotMapArc,
  DotMapPin,
} from "@/components/portfolio/dot-map"

<DotMap label="World map: based in Lisbon, with a client in New York">
  <DotMapArc from={{ lat: 38.72, lon: -9.14 }} to={{ lat: 40.71, lon: -74.0 }} />
  <DotMapPin lat={40.71} lon={-74.0} tone="muted">
    New York
  </DotMapPin>
  <DotMapPin lat={38.72} lon={-9.14} pulse>
    Lisbon
  </DotMapPin>
</DotMap>
```

## Examples

### Demo

“Based in, working everywhere”: home pulses, clients sit quietly around the world (hover, focus or tap the map for their names), and arcs connect them.

```tsx
import { DotMap, DotMapArc, DotMapPin } from "@/components/portfolio/dot-map"
import { typography } from "@/lib/typography"

const home = { lat: 38.72, lon: -9.14 }

const clients = [
  { city: "New York", lat: 40.71, lon: -74.0, side: "top" },
  { city: "San Francisco", lat: 37.77, lon: -122.42, side: "bottom" },
  { city: "Berlin", lat: 52.52, lon: 13.4, side: "right" },
  { city: "Tokyo", lat: 35.68, lon: 139.69, side: "bottom" },
  { city: "Sydney", lat: -33.87, lon: 151.21, side: "left" },
] as const

export default function DotMapDemo() {
  return (
    <div className="mx-auto flex w-full max-w-4xl flex-col gap-4 rounded-2xl border bg-card p-5 shadow-card md:gap-2 md:p-6">
      <div className="flex flex-wrap items-end justify-between gap-4">
        <div className="flex flex-col gap-2">
          <p className={typography.eyebrow}>Based in Lisbon</p>
          <h3 className={typography.heading}>Working with teams on four continents</h3>
        </div>
        <p className={typography.meta}>UTC+0 · 5 clients</p>
      </div>
      <DotMap label="World map: based in Lisbon, with clients in New York, San Francisco, Berlin, Tokyo and Sydney">
        {clients.map((c) => (
          <DotMapArc key={`arc-${c.city}`} from={home} to={c} />
        ))}
        {clients.map((c) => (
          <DotMapPin key={c.city} lat={c.lat} lon={c.lon} tone="muted" side={c.side} showLabel={false}>
            {c.city}
          </DotMapPin>
        ))}
        <DotMapPin lat={home.lat} lon={home.lon} pulse side="bottom">
          Lisbon
        </DotMapPin>
      </DotMap>
    </div>
  )
}
```

### Region

Crop to a region with `bounds`: here a summer of workshops across Europe, joined by dashed arcs.

```tsx
import { DotMap, DotMapArc, DotMapPin } from "@/components/portfolio/dot-map"

const stops = [
  { city: "Lisbon", lat: 38.72, lon: -9.14, side: "bottom" },
  { city: "Barcelona", lat: 41.39, lon: 2.17, side: "bottom" },
  { city: "Amsterdam", lat: 52.37, lon: 4.9, side: "left" },
  { city: "Copenhagen", lat: 55.68, lon: 12.57, side: "top" },
  { city: "Vienna", lat: 48.21, lon: 16.37, side: "right" },
] as const

export default function DotMapRegion() {
  return (
    <DotMap
      label="Map of Europe with five workshop stops from Lisbon to Vienna"
      listLabel="Workshop stops"
      bounds={[-14, 34, 34, 62]}
      className="mx-auto max-w-2xl"
    >
      {stops.slice(1).map((stop, i) => (
        <DotMapArc key={stop.city} from={stops[i]} to={stop} dashed bend={0.2} />
      ))}
      {stops.map((stop, i) => (
        <DotMapPin key={stop.city} lat={stop.lat} lon={stop.lon} side={stop.side} tone={i === 0 ? "highlight" : "muted"}>
          <span className="mr-1 font-mono text-muted-foreground">{String(i + 1).padStart(2, "0")}</span>{" "}
          {stop.city}
        </DotMapPin>
      ))}
    </DotMap>
  )
}
```

### Current location

Just one pulsing pin: a “currently in” card for an about page or a footer.

```tsx
import { DotMap, DotMapPin } from "@/components/portfolio/dot-map"

export default function DotMapCurrentLocation() {
  return (
    <figure className="flex w-full max-w-md flex-col gap-4 rounded-2xl border bg-card p-4 shadow-card md:p-5">
      <DotMap label="World map with a pin on Kyoto">
        <DotMapPin lat={35.01} lon={135.77} pulse showLabel={false}>
          Kyoto
        </DotMapPin>
      </DotMap>
      <figcaption className="flex items-baseline justify-between gap-4 border-t pt-4">
        <span className="font-mono text-xs tracking-[0.16em] text-muted-foreground uppercase">Currently in</span>
        <span className="text-sm font-medium">Kyoto, until March</span>
      </figcaption>
    </figure>
  )
}
```

## API Reference

### DotMap

The map. Put `<DotMapPin>`s and `<DotMapArc>`s inside (as direct children). Its height follows
its width (the aspect ratio of `bounds`), so size it by width with `className` (`w-full`,
`max-w-3xl`…); a fixed height would crop the dots but not move the pins. Arcs draw and pulses
start the first time the map scrolls into view. When a pin hides its label, the map becomes one
keyboard stop: focusing it (or tapping it) shows every hidden label, and Escape hides them again.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | — | Names the map for screen readers, e.g. "Map of the cities I've worked in". The pins are listed inside it. |
| `listLabel` | `string` | `"Locations"` | Accessible name of the list of pins. |
| `bounds` | `[west: number, south: number, east: number, north: number]` | — | Crop to a region: `[west, south, east, north]` in degrees, e.g. `[-25, 34, 45, 72]` for Europe. Defaults to the world (84°N–58°S). |

Also accepts every `div` prop.

### DotMapPin

A pin with a label (its children). Must be a direct child of `<DotMap>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lat` (required) | `number` | — | Latitude in degrees (north is positive). |
| `lon` (required) | `number` | — | Longitude in degrees (east is positive). |
| `tone` | `"highlight" \| "muted"` | `"highlight"` | `highlight` for the places that matter most (home, now); `muted` for the rest (clients, trips). |
| `pulse` | `boolean` | `false` | A ring that pulses twice around the pin when the map comes into view, e.g. for where you are right now. Off for reduced motion. |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Where the label sits relative to the pin. When it would cover another label or pin, the map moves it to a clearer side. |
| `showLabel` | `boolean` | `true` | Show the label next to the pin. When off, the label appears on hover, when the map has keyboard focus or is tapped (Escape hides it) and in print; screen readers always read it. |

Also accepts every `li` prop.

### DotMapArc

A curved line between two places (a move, a trip, a remote client). Draws itself (dashed arcs fade
in) the first time the map scrolls into view; drawn at once for reduced motion and in print. Must be
a direct child of `<DotMap>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `from` (required) | `LatLon` | — | Start point. |
| `to` (required) | `LatLon` | — | End point. |
| `bend` | `number` | `0.3` | How far the arc bows, as a share of its length. |
| `dashed` | `boolean` | `false` | Dashed line instead of solid. |

Also accepts every `path` prop.

### type LatLon

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `lat` (required) | `number` | — |  |
| `lon` (required) | `number` | — |  |

## Used in templates

- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)



---

# Draggable Canvas

> An endless canvas of project tiles you drag, flick, scroll or arrow around, the award-site signature. Without JavaScript it’s a plain grid.

Category: Work · Registry item: `@portfolio-kit/draggable-canvas` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/draggable-canvas) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/draggable-canvas.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/draggable-canvas
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/draggable-canvas.tsx` and the kit items it uses: `use-composed-refs`, `use-reduced-motion`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import {
  DraggableCanvas,
  DraggableCanvasCaption,
  DraggableCanvasItem,
  DraggableCanvasMedia,
} from "@/components/portfolio/draggable-canvas"

<DraggableCanvas label="Selected work" height="100svh">
  <DraggableCanvasItem href="/work/fieldnote">
    <DraggableCanvasMedia>
      <img src="/work/fieldnote.jpg" alt="" />
    </DraggableCanvasMedia>
    <DraggableCanvasCaption>
      <span>Fieldnote</span>
      <span>2025</span>
    </DraggableCanvasCaption>
  </DraggableCanvasItem>
</DraggableCanvas>
```

## Examples

### Demo

An endless plane of projects: drag or flick it, scroll with a trackpad, or tab through the tiles. Clicking a tile opens the project; dragging across one doesn’t.

```tsx
import {
  DraggableCanvas,
  DraggableCanvasCaption,
  DraggableCanvasItem,
  DraggableCanvasMedia,
} from "@/components/portfolio/draggable-canvas"
import { GenerativeArt } from "@/components/portfolio/generative-art"

const projects = [
  { slug: "lumen", title: "Lumen", year: 2025, art: "interface", hue: 250 },
  { slug: "tidewater", title: "Tidewater", year: 2025, art: "interface", hue: 195 },
  { slug: "orbit", title: "Orbit", year: 2024, art: "interface", hue: 20 },
  { slug: "fieldnote", title: "Fieldnote", year: 2024, art: "bauhaus", hue: 132 },
  { slug: "kiln", title: "Kiln Ceramics", year: 2023, art: "landscape", hue: 330 },
  { slug: "paperplane", title: "Paperplane", year: 2023, art: "rings", hue: 290 },
  { slug: "halcyon", title: "Halcyon", year: 2022, art: "landscape", hue: 85 },
  { slug: "meridian", title: "Meridian", year: 2022, art: "bauhaus", hue: 115 },
] as const

export default function DraggableCanvasDemo() {
  return (
    <DraggableCanvas label="Selected work" height="100svh">
      {projects.map((project) => (
        <DraggableCanvasItem key={project.slug} href={`#${project.slug}`}>
          <DraggableCanvasMedia>
            <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
          </DraggableCanvasMedia>
          <DraggableCanvasCaption>
            <span>{project.title}</span>
            <span>{project.year}</span>
          </DraggableCanvasCaption>
        </DraggableCanvasItem>
      ))}
    </DraggableCanvas>
  )
}
```

### Bounded

`wrap={false}` makes a finite board that bounces softly at its edges, and `wheel={false}` lets the page keep scrolling over it. Here in a card, with landscape tiles.

```tsx
import {
  DraggableCanvas,
  DraggableCanvasCaption,
  DraggableCanvasItem,
  DraggableCanvasMedia,
} from "@/components/portfolio/draggable-canvas"
import { GenerativeArt } from "@/components/portfolio/generative-art"

const experiments = [
  { slug: "type-tester", title: "Type tester", kind: "Tool", art: "bauhaus" },
  { slug: "gradient-lab", title: "Gradient lab", kind: "Study", art: "mesh" },
  { slug: "orbit-loader", title: "Orbit loader", kind: "Motion", art: "rings" },
  { slug: "tide-synth", title: "Tide synth", kind: "Audio", art: "waves" },
  { slug: "glass-orb", title: "Glass orb", kind: "WebGL", art: "orb" },
  { slug: "grid-poster", title: "Grid poster", kind: "Print", art: "bauhaus" },
] as const

export default function DraggableCanvasBounded() {
  return (
    <div className="mx-auto w-full max-w-4xl overflow-hidden rounded-2xl border bg-card shadow-card">
      <DraggableCanvas label="Experiments" wrap={false} wheel={false} columns={3} tileWidth={300} gap={24} height="440px">
        {experiments.map((item) => (
          <DraggableCanvasItem key={item.slug} href={`#${item.slug}`}>
            <DraggableCanvasMedia className="aspect-video">
              <GenerativeArt seed={item.slug} variant={item.art} />
            </DraggableCanvasMedia>
            <DraggableCanvasCaption>
              <span>{item.title}</span>
              <span>{item.kind}</span>
            </DraggableCanvasCaption>
          </DraggableCanvasItem>
        ))}
      </DraggableCanvas>
    </div>
  )
}
```

## API Reference

### DraggableCanvas

The canvas. Tiles sit on a staggered grid (odd columns drop by half a tile). Drag with a mouse or
finger (it keeps gliding when you let go), scroll with a wheel or trackpad, or focus the canvas and
use the arrow keys (Shift for bigger steps); tabbing to a tile brings it into view. Before hydration, and
without JavaScript, the same tiles render as an ordinary responsive grid. On touch screens a swipe that
starts vertically still scrolls the page and two fingers still pinch-zoom; a swipe that starts sideways
pans the canvas (in any direction after that). With reduced motion the canvas stops where you let go
(no glide) and keyboard and focus moves jump instead of easing.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Projects"` | Accessible name of the canvas region, e.g. "Selected work". |
| `wrap` | `boolean` | `true` | Repeat the tiles in every direction so the canvas never ends. Off: the canvas stops (with a soft bounce) at its edges. |
| `columns` | `number` | `4` | Tiles per row before the pattern repeats. |
| `tileWidth` | `number` | `280` | Tile width in px (shrinks to 60% of the canvas on narrow screens). |
| `gap` | `number` | `32` | Space between tiles, in px. |
| `height` | `string` | `"min(80svh, 720px)"` | Canvas height (any CSS length). |
| `wheel` | `boolean` | `true` | Pan with the mouse wheel / trackpad. With `wrap`, the wheel always pans the canvas; with `wrap={false}` it hands the scroll back to the page once the board reaches its edge. Turn it off if the canvas sits in a long page and should never take the wheel. |
| `hint` | `React.ReactNode` | `"Drag to explore"` | Small pill shown until the first drag. `null` hides it. Decorative: screen readers get `instructions`. |
| `instructions` | `string` | — | How to use the canvas, read to screen-reader users (the visible `hint` is hidden from them). Default: "Drag, scroll or use the arrow keys to pan. Tab moves between projects." ("scroll" is left out when `wheel` is off). |
| `children` | `React.ReactNode` | — | `<DraggableCanvasItem>`s, as direct children. |

Also accepts every `div` prop.

### DraggableCanvasItem

One tile: a link wrapping a `<DraggableCanvasMedia>` and an optional `<DraggableCanvasCaption>`.
Dragging across it never follows the link; a plain click or Enter does.

Also accepts every `a` prop.

### DraggableCanvasMedia

Cover of a tile (4:5 by default; change it with `className`, e.g. `aspect-video`). Put an `<img>` or
`<GenerativeArt />` inside; it zooms gently on hover and settles back while you drag.

Also accepts every `div` prop.

### DraggableCanvasCaption

A row under the cover: the project name first, then quieter details (year, client).

Also accepts every `div` prop.



---

# Expanding Panels

> A row of tall project panels: hover or focus one and it widens to show its title and details while the others fold into vertical labels. Stacks into an accordion on phones.

Category: Work · Registry item: `@portfolio-kit/expanding-panels` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/expanding-panels) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/expanding-panels.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/expanding-panels
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/expanding-panels.tsx`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import {
  ExpandingPanel,
  ExpandingPanels,
} from "@/components/portfolio/expanding-panels"

<ExpandingPanels>
  <ExpandingPanel href="/work/fieldnote" name="Fieldnote" meta="2025 · Halcyon Labs" description="A calmer research notebook.">
    <img src="/work/fieldnote.jpg" alt="" />
  </ExpandingPanel>
  <ExpandingPanel href="/work/tidewater" name="Tidewater" meta="2024 · Tidewater" description="Dashboards for harbour ops.">
    <img src="/work/tidewater.jpg" alt="" />
  </ExpandingPanel>
</ExpandingPanels>
```

## Examples

### Demo

Five projects side by side: hover, tab or use the arrow keys and each one opens to show what it is. On phones they stack, and the first tap opens a panel.

```tsx
import { ExpandingPanel, ExpandingPanels } from "@/components/portfolio/expanding-panels"
import { GenerativeArt } from "@/components/portfolio/generative-art"

const projects = [
  { slug: "lumen", name: "Lumen", meta: "2025 · Halcyon Labs", description: "A design system for eleven products.", art: "interface", hue: 250 },
  { slug: "tidewater", name: "Tidewater", meta: "2025 · Tidewater Energy", description: "Grid monitoring for coastal wind farms.", art: "interface", hue: 195 },
  { slug: "orbit", name: "Orbit", meta: "2024 · Open source", description: "A tiny, accessible command palette.", art: "interface", hue: 20 },
  { slug: "fieldnote", name: "Fieldnote", meta: "2024 · Fieldnote", description: "A launch campaign printed in risograph.", art: "bauhaus", hue: 132 },
  { slug: "kiln", name: "Kiln Ceramics", meta: "2023 · Kiln", description: "A storefront where every product is a portrait.", art: "landscape", hue: 330 },
] as const

export default function ExpandingPanelsDemo() {
  return (
    <ExpandingPanels className="mx-auto w-full max-w-6xl">
      {projects.map((p) => (
        <ExpandingPanel key={p.slug} href={`#${p.slug}`} name={p.name} meta={p.meta} description={p.description}>
          <GenerativeArt seed={p.slug} variant={p.art} hue={p.hue} />
        </ExpandingPanel>
      ))}
    </ExpandingPanels>
  )
}
```

### With video

Put a `<HoverVideo>` in a panel and its clip plays while that panel is open under the pointer or focus.

```tsx
import { ExpandingPanel, ExpandingPanels } from "@/components/portfolio/expanding-panels"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { HoverVideo } from "@/components/portfolio/hover-video"

export default function ExpandingPanelsWithVideo() {
  return (
    <ExpandingPanels defaultActive={1} className="mx-auto w-full max-w-4xl md:h-[420px]">
      <ExpandingPanel href="#reel" name="Showreel" meta="2026 · 1:42">
        {/* Your clip: a file in public/ or a CDN URL. The demo clip sits next to the docs preview. */}
        <HoverVideo src="media/showreel.mp4">
          <GenerativeArt seed="reel-panel" variant="landscape" hue={250} />
        </HoverVideo>
      </ExpandingPanel>
      <ExpandingPanel href="#titles" name="Title design" meta="2025 · Northwind Films">
        <GenerativeArt seed="titles" variant="bauhaus" />
      </ExpandingPanel>
      <ExpandingPanel href="#loops" name="Product loops" meta="2024 · Orbit">
        <GenerativeArt seed="loops" variant="rings" />
      </ExpandingPanel>
    </ExpandingPanels>
  )
}
```

## API Reference

### ExpandingPanels

The row (`<ul>`). Direct children must be `<ExpandingPanel>`s. From `md` up, panels share the width and
the active one grows; below `md` they stack and the active one opens. Each panel is a tab stop, and the
arrow keys, Home and End also move between panels (←/→ follow the reading direction in RTL).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultActive` | `number` | `0` | Panel open at first (and when nothing is hovered or focused yet), counted from 0. |
| `active` | `number` | — | The open panel, when you control it. Pair with `onActiveChange`. |
| `onActiveChange` | `(index: number) => void` | — | Called with the panel's index when hover, focus or a tap opens it. |

Also accepts every `ul` prop.

### ExpandingPanel

One project: a real link that fills the panel. Folded, it shows its number and a vertical name; open,
the media brightens and the title, details and an arrow slide in. On touch screens the first tap opens
a folded panel and the second follows the link; mouse clicks and Enter always follow it. Screen readers
hear `name` as the link text and `meta` and `description` as its description.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Project name: the vertical label when folded, the title when open. |
| `meta` | `React.ReactNode` | — | Small details shown when open, e.g. "2025 · Halcyon Labs". |
| `description` | `React.ReactNode` | — | One line shown when open. |
| `children` | `React.ReactNode` | — | Media filling the panel: `<GenerativeArt />`, an `<img>` or a `<HoverVideo>`. |

Also accepts every `a` prop.



---

# Experience

> Work history as a hover-focus list, a vertical timeline that marks the current role, or compact résumé rows.

Category: About · Registry item: `@portfolio-kit/experience` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/experience) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/experience.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/experience
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/experience.tsx` and the kit items it uses: `format`, `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  ExperienceItem,
  ExperienceList,
} from "@/components/portfolio/experience"

<ExperienceList>
  <ExperienceItem
    company="Halcyon Labs"
    position="Staff Design Engineer"
    start="2022-03"
    location="Remote"
    description="Lead the Lumen design system."
    tags={["React", "Design tokens"]}
  />
  <ExperienceItem company="Paperplane Studio" position="Senior Product Designer" start="2019-01" end="2022-02" />
</ExperienceList>
```

## Examples

### Demo

Work history as a hover-focus list: the hovered role lifts onto a card while the others dim, and each row links to the company.

```tsx
import { ExperienceItem, ExperienceList } from "@/components/portfolio/experience"

const jobs = [
  {
    company: "Halcyon Labs",
    position: "Staff Design Engineer",
    start: "2022-03",
    location: "Remote",
    description: "Lead the Lumen design system; partner with 11 product teams on UI architecture, accessibility and motion.",
    tags: ["React", "TypeScript", "Design tokens"],
    href: "#halcyon",
  },
  {
    company: "Paperplane Studio",
    position: "Senior Product Designer",
    start: "2019-01",
    end: "2022-02",
    location: "Lisbon",
    description: "Shipped products for fintech and climate clients, from first sketch to production code.",
    tags: ["Product design", "Prototyping", "Next.js"],
    href: "#paperplane",
  },
  {
    company: "Meridian Health",
    position: "Front-end Engineer",
    start: "2016-06",
    end: "2018-12",
    location: "Porto",
    description: "Built the patient portal used by 400k people and led the migration to a shared component library.",
    tags: ["Vue", "Accessibility", "Testing"],
    href: "#meridian",
  },
]

export default function ExperienceDemo() {
  return (
    <ExperienceList className="mx-auto w-full max-w-3xl px-4 py-8 md:px-6">
      {jobs.map((job) => (
        <ExperienceItem key={job.company} {...job} />
      ))}
    </ExperienceList>
  )
}
```

### Timeline

Roles on a vertical rail with a pulsing dot on the current job. Reads as a career story on an about page.

```tsx
import { ExperienceItem, ExperienceList } from "@/components/portfolio/experience"

const jobs = [
  {
    position: "Staff Design Engineer",
    company: "Halcyon Labs",
    href: "#halcyon",
    start: "2022",
    location: "Remote",
    description: "Lead the Lumen design system across eleven products and 140 engineers.",
    tags: ["React", "Design tokens"],
  },
  {
    position: "Senior Product Designer",
    company: "Paperplane Studio",
    href: "#paperplane",
    start: "2019",
    end: "2022",
    location: "Lisbon",
    description: "Took fintech and climate products from first sketch to production code.",
  },
  {
    position: "Front-end Engineer",
    company: "Meridian Health",
    start: "2016",
    end: "2019",
    location: "Porto",
    description: "Built a patient portal used by 400k people.",
  },
]

export default function ExperienceTimeline() {
  return (
    <ExperienceList variant="timeline" className="w-full max-w-xl">
      {jobs.map((job) => (
        <ExperienceItem key={job.company} {...job} />
      ))}
    </ExperienceList>
  )
}
```

### Compact

One line per role with dotted leaders to the dates. A résumé at a glance for sidebars or the end of a long about page.

```tsx
import { ExperienceItem, ExperienceList } from "@/components/portfolio/experience"

const roles = [
  { position: "Staff Design Engineer", company: "Halcyon Labs", start: "2022-03", href: "#halcyon" },
  { position: "Senior Product Designer", company: "Paperplane Studio", start: "2019-01", end: "2022-02" },
  { position: "Front-end Engineer", company: "Meridian Health", start: "2016-06", end: "2018-12" },
  { position: "Design Intern", company: "Northpeak", start: "2015-06", end: "2015-09" },
]

export default function ExperienceCompact() {
  return (
    <ExperienceList variant="compact" className="w-full max-w-xl">
      {roles.map((item) => (
        <ExperienceItem key={item.company} {...item} />
      ))}
    </ExperienceList>
  )
}
```

### Résumé Section

A full résumé section: the career story on a timeline beside compact rows for earlier roles.

```tsx
import { ExperienceItem, ExperienceList } from "@/components/portfolio/experience"
import { Section, SectionEyebrow, SectionHeader, SectionTitle } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

const recent = [
  {
    position: "Staff Design Engineer",
    company: "Halcyon Labs",
    href: "#halcyon",
    start: "2022",
    location: "Remote",
    description: "Lead the Lumen design system; partner with product teams on UI architecture and motion.",
  },
  {
    position: "Senior Product Designer",
    company: "Paperplane Studio",
    start: "2019",
    end: "2022",
    location: "Lisbon",
    description: "Shipped fintech and climate products from first sketch to production.",
  },
]

const earlier = [
  { position: "Front-end Engineer", company: "Meridian Health", start: "2016-06", end: "2018-12" },
  { position: "Design Intern", company: "Northpeak", start: "2015-06", end: "2015-09" },
  { position: "Freelance Web Designer", company: "Self-employed", start: "2013-02", end: "2015-05" },
]

export default function ExperienceResume() {
  return (
    <Section spacing="sm">
      <div className="grid gap-14 lg:grid-cols-2 lg:gap-16">
        <div className="flex flex-col gap-10">
          <SectionHeader>
            <SectionEyebrow index={3}>Experience</SectionEyebrow>
            <SectionTitle className="md:text-4xl">Where I&rsquo;ve worked</SectionTitle>
          </SectionHeader>
          <ExperienceList variant="timeline">
            {recent.map((job) => (
              <ExperienceItem key={job.company} {...job} />
            ))}
          </ExperienceList>
        </div>
        <div className="flex flex-col gap-6 lg:pt-2">
          <p className={typography.eyebrow}>Earlier</p>
          <ExperienceList variant="compact">
            {earlier.map((job) => (
              <ExperienceItem key={job.company} {...job} />
            ))}
          </ExperienceList>
        </div>
      </div>
    </Section>
  )
}
```

## API Reference

### ExperienceList

An ordered list of roles, most recent first. Every `ExperienceItem` inside follows its `variant`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"list" \| "timeline" \| "compact" \| null` | `"list"` | `list`: dates beside each role; the hovered (or keyboard-focused) role lifts onto a card and, on hover, the others dim. `timeline`: a vertical rail; the current role's dot is highlighted and pulses a few times. `compact`: one line per role with dotted leaders to the dates. |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading element for each role. Pick the level below the section's heading. |

Also accepts every `ol` prop.

### ExperienceItem

One role. Dates become `<time>` elements; a role without an `end` is marked current.
Extra children render under the description (e.g. a list of highlights).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `start` (required) | `string` | — | Start date: "2022", "2022-03" (shown as "Mar 2022") or free text. |
| `position` (required) | `React.ReactNode` | — | Job title or position held, e.g. "Senior Designer". |
| `company` (required) | `React.ReactNode` | — | Company or client name. |
| `end` | `string` | — | End date, formatted like `start`. Omit it for the current role (shown as `presentLabel`); "Present", "Now" and "Current" also mark the role current and are shown as written. |
| `current` | `boolean` | — | Force the current state (highlighted dot in the timeline). Inferred from `end` by default; set it when `end` is a translated word such as "Heute". |
| `presentLabel` | `string` | `"Present"` | Text for the end of a current role without an `end`. |
| `toLabel` | `string` | `"to"` | Word screen readers hear between the start and end dates (shown as a dash). |
| `href` | `string` | — | Company URL. In the list variant the whole item becomes the link. Absolute URLs open in a new tab. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added to the company link when `href` opens in a new tab. Translate it here. |
| `location` | `React.ReactNode` | — | City, "Remote"… Hidden in the compact variant. |
| `description` | `React.ReactNode` | — | A sentence or two about the role. Hidden in the compact variant. |
| `tags` | `string[]` | — | Skills or tools, shown as small pills. Hidden in the compact variant. |
| `tagsLabel` | `string` | `"Skills"` | Accessible name of the tag list. |
| `locale` | `string` | `"en-US"` | Locale for month names. |

Also accepts every `li` prop.

## Used in templates

- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)
- [Résumé](https://www.parthjadhav.com/products/portfolio-kit/templates/resume.md)



---

# FAQ

> Accordion of questions and answers, as ruled lines or cards, with optional FAQPage JSON-LD for search engines.

Category: Services · Registry item: `@portfolio-kit/faq` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/faq) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/faq.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/faq
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/faq.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`, `radix-ui`.

## Usage

```tsx
import { Faq, FaqItem } from "@/components/portfolio/faq"

<Faq>
  <FaqItem question="Do you take on small projects?" answer="Yes: audits and two-week sprints are a good fit." />
  <FaqItem question="Where are you based?" answer="Lisbon, working with teams across Europe." />
</Faq>
```

## Examples

### Demo

Answer the questions clients ask before they email you. One answer open at a time, fully keyboard accessible.

```tsx
import { Faq, FaqItem } from "@/components/portfolio/faq"

const faqs = [
  {
    question: "Are you available for new projects?",
    answer: "Yes — I'm booking projects from next quarter. Small audits and advisory calls can usually start within two weeks.",
  },
  {
    question: "What does a typical engagement cost?",
    answer:
      "Most projects land between €8k and €40k depending on scope. After a short call I send a fixed-price proposal, so there are no surprises.",
  },
  {
    question: "Do you work with agencies?",
    answer: "Often. I'm happy to work white-label as part of your team, in your tools and your process.",
  },
  {
    question: "What happens after launch?",
    answer: "Every project includes 30 days of support. After that, an optional monthly retainer covers fixes and small improvements.",
  },
]

export default function FaqDemo() {
  return (
    <Faq defaultValue={faqs[0].question} className="w-full max-w-2xl">
      {faqs.map((faq) => (
        <FaqItem key={faq.question} question={faq.question} answer={faq.answer} />
      ))}
    </Faq>
  )
}
```

### Cards

Each question in its own card. Softer, and good on muted or patterned backgrounds.

```tsx
import { Faq, FaqItem } from "@/components/portfolio/faq"

const faqs = [
  {
    question: "Which tools and stack do you use?",
    answer: "Figma for design; React, TypeScript, Next.js and Tailwind for build. I adapt to your stack when it makes sense.",
  },
  {
    question: "How do we communicate during a project?",
    answer: "A shared Slack channel, a short Loom every Friday and a live staging link from week one. No status meetings.",
  },
  {
    question: "Can you work in our timezone?",
    answer: "I'm based in Lisbon (GMT+1) and overlap comfortably with Europe and the US East Coast mornings.",
  },
]

export default function FaqCards() {
  return (
    <Faq variant="cards" defaultValue={faqs[1].question} className="w-full max-w-2xl">
      {faqs.map((faq) => (
        <FaqItem key={faq.question} question={faq.question} answer={faq.answer} />
      ))}
    </Faq>
  )
}
```

### Two Column

A pinned heading beside the questions, rich answers with links, and FAQPage JSON-LD so search engines can show them.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { Faq, FaqItem } from "@/components/portfolio/faq"
import {
  Section,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const faqs = [
  {
    question: "Are you available for new projects?",
    answer: "Yes — I'm booking projects from next quarter. Small audits and advisory calls can usually start within two weeks.",
  },
  {
    question: "What does a typical engagement cost?",
    answer:
      "Most projects land between €8k and €40k depending on scope. After a short call I send a fixed-price proposal, so there are no surprises.",
  },
  {
    question: "Do you sign NDAs?",
    answer: "Of course — send yours over before our first call, or I can share a simple mutual one.",
  },
]

export default function FaqTwoColumn() {
  return (
    <Section>
      <div className="grid gap-10 lg:grid-cols-[minmax(0,1fr)_minmax(0,1.5fr)] lg:gap-20">
        <SectionHeader className="lg:sticky lg:top-24 lg:self-start">
          <SectionEyebrow index={6}>FAQ</SectionEyebrow>
          <SectionTitle>Questions, answered</SectionTitle>
          <SectionDescription>Can&apos;t find what you&apos;re looking for? Just ask — I reply within a day.</SectionDescription>
          <ArrowLink href="mailto:hello@example.com" className="mt-2">
            hello@example.com
          </ArrowLink>
        </SectionHeader>
        <Faq schema defaultValue={faqs[0].question}>
          {faqs.map((faq) => (
            <FaqItem key={faq.question} question={faq.question} answer={faq.answer} />
          ))}
          <FaqItem
            question="Can I see more work?"
            schemaAnswer="Yes. Some projects are under NDA, so I'm happy to walk through them on a call."
          >
            <p>
              Yes. Some projects are under NDA, so I&apos;m happy to walk through them on a call —{" "}
              <a href="#contact">book a time</a>.
            </p>
          </FaqItem>
        </Faq>
      </div>
    </Section>
  )
}
```

## API Reference

### Faq

The accordion root. Children are `FaqItem`s. Each question is a button inside a heading; Enter or
Space toggles it, ↑/↓ move between questions and Home/End jump to the first and last. Closed
answers are left out of the page until opened, except when printing: then every answer shows.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"lines" \| "cards"` | `"lines"` | `lines`: questions separated by hairlines, for a quiet section. `cards`: each question in its own card, for FAQs beside other cards. |
| `schema` | `boolean` | `false` | Emit FAQPage structured data built from each item's `question` and `answer` (or `schemaAnswer`). Add it once per page, only for questions you answer yourself. Search engines show FAQ rich results for a limited set of sites, but the markup still describes the page. |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of every question, so the FAQ fits your page outline (`h4` under an `h3`). An item's own `headingLevel` wins. |
| `type` | `"single" \| "multiple"` | `"single"` | `single` keeps one answer open at a time (click again to close); `multiple` lets any number stay open. |
| `value` | `string \| string[]` | — | Open item (controlled): the item's `value`, which defaults to its question text. |
| `defaultValue` | `string \| string[]` | — | Item open on first render (uncontrolled), e.g. the first question. |
| `onValueChange` | `((value: string) => void) \| ((value: string[]) => void)` | — | Called with the open item's value (`""` when all are closed). |

Also accepts every `Accordion.Root` prop.

### FaqItem

One question and its answer.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `question` (required) | `React.ReactNode` | — | The question, rendered as the heading and the toggle button. |
| `answer` | `React.ReactNode` | — | Answer content. Or pass children for rich answers (paragraphs, links, lists). |
| `value` | `string` | — | Unique value; defaults to the question text. |
| `schemaAnswer` | `string` | — | Plain-text answer for JSON-LD when the rendered answer is rich. |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | — | Heading level wrapping the question. Defaults to the `Faq`'s `headingLevel` (`h3`). |

Also accepts every `Accordion.Item` prop.

## Used in templates

- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)



---

# Filter Chips

> Single- or multi-select pill chips with optional counts — for filtering projects, posts or tags by category. Arrow-key navigable.

Category: Utilities · Registry item: `@portfolio-kit/filter-chips` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/filter-chips) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/filter-chips.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/filter-chips
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/filter-chips.tsx`.

npm dependencies: `class-variance-authority`, `lucide-react`, `radix-ui`.

## Usage

```tsx
import {
  FilterChip,
  FilterChips,
} from "@/components/portfolio/filter-chips"

<FilterChips type="single" defaultValue="all" required aria-label="Filter by category">
  <FilterChip value="all" label="All" count={12} />
  <FilterChip value="product" label="Product" count={7} />
  <FilterChip value="branding" label="Branding" count={5} />
</FilterChips>
```

## Examples

### Demo

Single-select category filter with counts. `required` keeps one chip active, and arrow keys move between chips.

```tsx
import * as React from "react"

import { FilterChip, FilterChips } from "@/components/portfolio/filter-chips"

const projects = [
  { title: "Lumen", category: "Product", year: 2025 },
  { title: "Tidewater", category: "Product", year: 2025 },
  { title: "Fieldnote", category: "Brand", year: 2024 },
  { title: "Orbit", category: "Open source", year: 2024 },
]

const categories = ["All", "Product", "Brand", "Open source"]

export default function FilterChipsDemo() {
  const [category, setCategory] = React.useState("All")
  const visible = category === "All" ? projects : projects.filter((p) => p.category === category)

  return (
    <div className="flex w-full max-w-lg flex-col gap-6">
      <FilterChips type="single" required value={category} onValueChange={setCategory} aria-label="Filter by category">
        {categories.map((c) => (
          <FilterChip
            key={c}
            value={c}
            label={c}
            count={c === "All" ? projects.length : projects.filter((p) => p.category === c).length}
          />
        ))}
      </FilterChips>
      <ul role="list" className="divide-y border-y">
        {visible.map((project) => (
          <li key={project.title} className="flex items-baseline justify-between gap-4 py-3">
            <span className="font-medium">{project.title}</span>
            <span className="font-mono text-xs text-muted-foreground tabular-nums">
              {project.category} · {project.year}
            </span>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

### Multiple

`type="multiple"` for combinable filters — a check mark grows in on each active chip. Pair it with a clear action.

```tsx
import * as React from "react"

import { FilterChip, FilterChips } from "@/components/portfolio/filter-chips"

const stack = ["React", "TypeScript", "Motion", "WebGL", "Figma", "Rust", "Tokens"]

export default function FilterChipsMultiple() {
  const [selected, setSelected] = React.useState<string[]>(["React", "Motion"])

  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <div className="flex items-baseline justify-between gap-4">
        <p className="font-mono text-xs text-muted-foreground">
          {selected.length ? `${selected.length} selected` : "Showing everything"}
        </p>
        <button
          type="button"
          onClick={() => setSelected([])}
          disabled={!selected.length}
          className="rounded-sm py-0.5 text-sm font-medium text-muted-foreground outline-none transition-colors hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50"
        >
          Clear
        </button>
      </div>
      <FilterChips type="multiple" value={selected} onValueChange={setSelected} aria-label="Filter by technology">
        {stack.map((tech) => (
          <FilterChip key={tech} value={tech} label={tech} />
        ))}
      </FilterChips>
    </div>
  )
}
```

### Small & Uncontrolled

`size="sm"` for dense toolbars; `defaultValue` when you don't need the state. Disabled chips stay visible but inert.

```tsx
import { FilterChip, FilterChips } from "@/components/portfolio/filter-chips"

export default function FilterChipsSmall() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3 border-b pb-4">
      <div className="flex items-baseline justify-between gap-4">
        <p className="font-heading text-lg">Writing</p>
        <p className="font-mono text-xs text-muted-foreground">42 posts</p>
      </div>
      <FilterChips type="single" size="sm" defaultValue="2025" aria-label="Filter by year">
        <FilterChip value="2026" disabled>
          2026 · soon
        </FilterChip>
        {["2025", "2024", "2023", "Archive"].map((year) => (
          <FilterChip key={year} value={year}>
            {year}
          </FilterChip>
        ))}
      </FilterChips>
    </div>
  )
}
```

### Filtering a Grid

Chips above a grid of project cards — the typical “Work” page setup.

```tsx
import * as React from "react"

import { FilterChip, FilterChips } from "@/components/portfolio/filter-chips"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"

const projects = [
  { slug: "lumen", title: "Lumen", category: "Product", year: 2025, art: "mesh", summary: "A design system powering eleven products." },
  { slug: "fieldnote", title: "Fieldnote", category: "Brand", year: 2024, art: "bauhaus", summary: "Identity for a research notes app." },
  { slug: "orbit", title: "Orbit", category: "Open source", year: 2024, art: "rings", summary: "A tiny, accessible command palette." },
  { slug: "tidewater", title: "Tidewater", category: "Product", year: 2025, art: "waves", summary: "Grid monitoring for coastal wind farms." },
] as const

const categories = ["All", "Product", "Brand", "Open source"]

export default function FilterChipsProjectGrid() {
  const [category, setCategory] = React.useState("All")
  const visible = category === "All" ? projects : projects.filter((p) => p.category === category)

  return (
    <div className="mx-auto flex max-w-4xl flex-col gap-8">
      <FilterChips type="single" required value={category} onValueChange={setCategory} aria-label="Filter projects">
        {categories.map((c) => (
          <FilterChip
            key={c}
            value={c}
            label={c}
            count={c === "All" ? projects.length : projects.filter((p) => p.category === c).length}
          />
        ))}
      </FilterChips>
      <div className="grid gap-6 sm:grid-cols-2">
        {visible.map((project) => (
          <ProjectCard key={project.slug} href={`#${project.slug}`}>
            <ProjectCardMedia>
              <GenerativeArt seed={project.slug} variant={project.art} />
            </ProjectCardMedia>
            <ProjectCardContent>
              <ProjectCardMeta>
                <span>{project.year}</span>
                <span>{project.category}</span>
              </ProjectCardMeta>
              <ProjectCardTitle>{project.title}</ProjectCardTitle>
              <ProjectCardDescription>{project.summary}</ProjectCardDescription>
            </ProjectCardContent>
          </ProjectCard>
        ))}
      </div>
    </div>
  )
}
```

## API Reference

### FilterChips

A group of toggleable chips. Give it an `aria-label`. `type="single"` is a radio group: arrow
keys move the selection, as with radio buttons. `type="multiple"` is a toolbar of toggle buttons
(`aria-pressed`): arrow keys move focus and Space/Enter toggles.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default"` | `"default"` | Chip size. `sm` suits dense toolbars and horizontal scrollers. |
| `required` | `boolean` | `false` | Keep at least one chip active — clicks that would clear the selection are ignored. Works controlled (`value` + `onValueChange`) and uncontrolled (`defaultValue`). |

Also accepts every `ToggleGroup.Root` prop.

### FilterChip

One chip. `value` is what the group reports on change; multi-select chips grow a check mark when active.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `React.ReactNode` | — | Visible text. `children` wins when both are passed. |
| `count` | `number` | — | Optional count badge, e.g. the number of matching projects. |

Also accepts every `ToggleGroup.Item` prop.

## Used in templates

- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)



---

# Fit Text

> Text that scales to exactly fill its container's width, for giant footer wordmarks and hero names. Each line fits on its own, with any font.

Category: Utilities · Registry item: `@portfolio-kit/fit-text` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/fit-text) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/fit-text.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/fit-text
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/fit-text.tsx` and the kit items it uses: `use-composed-refs`, `use-isomorphic-layout-effect`.

## Usage

```tsx
import { FitText, FitTextLine } from "@/components/portfolio/fit-text"

<FitText as="h1">
  <FitTextLine>Mara</FitTextLine>
  <FitTextLine>Lindqvist</FitTextLine>
</FitText>
```

## Examples

### Demo

The giant footer wordmark: your name set edge to edge, whatever the screen or font.

```tsx
import { FitText } from "@/components/portfolio/fit-text"
import { typography } from "@/lib/typography"

const links = ["Work", "About", "Journal", "Contact"]

export default function FitTextDemo() {
  return (
    <footer className="mx-auto flex w-full max-w-6xl flex-col gap-6 px-5 pt-10 pb-6 sm:px-6 md:gap-8 md:px-8">
      <div className="flex flex-wrap items-end justify-between gap-4 border-b pb-6">
        <div className="flex flex-col gap-1">
          <p className={typography.eyebrow}>Have a project in mind?</p>
          <a
            href="mailto:hello@example.com"
            className="rounded-sm font-heading text-xl underline decoration-foreground/30 underline-offset-[0.2em] outline-none transition-colors duration-200 ease-smooth hover:text-highlight-ink focus-visible:ring-[3px] focus-visible:ring-ring/50 md:text-2xl"
          >
            hello@example.com
          </a>
        </div>
        <nav aria-label="Footer">
          <ul role="list" className="flex flex-wrap gap-x-5 gap-y-2 text-sm">
            {links.map((link) => (
              <li key={link}>
                <a
                  href={`#${link.toLowerCase()}`}
                  className="inline-flex min-h-6 items-center rounded-sm text-muted-foreground outline-none transition-colors duration-200 ease-smooth hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50"
                >
                  {link}
                </a>
              </li>
            ))}
          </ul>
        </nav>
      </div>
      <FitText as="p">Mara Lindqvist</FitText>
      <div className="flex flex-wrap justify-between gap-2 border-t pt-4">
        <p className={typography.meta}>© 2026 Mara Lindqvist</p>
        <p className={typography.meta}>Made in Lisbon</p>
      </div>
    </footer>
  )
}
```

### Multiple Lines

Each `FitTextLine` fills the width on its own, so a short first name lands huge and a long surname smaller — the stacked poster look.

```tsx
import { FitText, FitTextLine } from "@/components/portfolio/fit-text"
import { typography } from "@/lib/typography"

export default function FitTextMultiLine() {
  return (
    <section className="mx-auto flex w-full max-w-4xl flex-col gap-6">
      <p className={typography.eyebrow}>Designer &amp; developer — Lisbon</p>
      <FitText as="h1" className="uppercase">
        <FitTextLine>Mara</FitTextLine>
        <FitTextLine>Lindqvist</FitTextLine>
        <FitTextLine className="text-muted-foreground">Studio</FitTextLine>
      </FitText>
    </section>
  )
}
```

### In Cards

It fits its container, not the viewport: headline numbers that fill each card of a grid, capped with `max`.

```tsx
import { FitText } from "@/components/portfolio/fit-text"
import { typography } from "@/lib/typography"

const stats = [
  { value: "12", label: "Years designing" },
  { value: "140", label: "Engineers on the system" },
  { value: "3.2M", label: "Monthly readers" },
]

export default function FitTextInCards() {
  return (
    <ul role="list" className="mx-auto grid w-full max-w-4xl gap-4 sm:grid-cols-3 md:gap-6">
      {stats.map((stat) => (
        <li key={stat.label} className="flex flex-col justify-between gap-4 rounded-2xl border bg-card p-5 text-card-foreground shadow-card md:p-6">
          <FitText as="p" max="7rem" className="tabular-nums">
            {stat.value}
          </FitText>
          <p className={typography.eyebrow}>{stat.label}</p>
        </li>
      ))}
    </ul>
  )
}
```

## API Reference

### FitText

The container. Pass a string to fit one line, or several `FitTextLine`s so each line fills the
width on its own ("Mara" huge, "Lindqvist" smaller). Uses the heading font with tight leading;
override with `className`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"div" \| "p" \| "h1" \| "h2" \| "h3" \| "span"` | `"div"` | Element to render: `h1`/`h2` for a hero name, `p` or `div` for a decorative wordmark. |
| `max` | `string` | — | Largest font-size any line may reach (any CSS length, e.g. `"12rem"`), for short words in wide containers. |

Also accepts every `div` prop.

### FitTextLine

One line that fills the container's width. Must be inside `FitText`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `max` | `string` | — | Override the root's `max` for this line. |

Also accepts every `span` prop.



---

# Floating Dock

> A macOS-style navigation dock. Icons grow toward the pointer, labels appear above them and the current page gets a dot.

Category: Navigation · Registry item: `@portfolio-kit/floating-dock` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/floating-dock) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/floating-dock.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/floating-dock
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/floating-dock.tsx` and the kit items it uses: `use-fine-pointer`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { BrandIcon } from "@/components/portfolio/brand-icons"
import {
  FloatingDock,
  FloatingDockItem,
  FloatingDockSeparator,
} from "@/components/portfolio/floating-dock"

<FloatingDock>
  <FloatingDockItem href="https://github.com/example" label="GitHub" icon={<BrandIcon name="github" />} />
  <FloatingDockItem href="https://dribbble.com/example" label="Dribbble" icon={<BrandIcon name="dribbble" />} />
  <FloatingDockSeparator />
  <FloatingDockItem href="https://www.linkedin.com/in/example" label="LinkedIn" icon={<BrandIcon name="linkedin" />} />
</FloatingDock>
```

## Examples

### Demo

Navigation pinned to the bottom of the viewport. Icons grow toward the pointer and the current page gets a dot.

```tsx
import * as React from "react"
import { BookOpen, Briefcase, Home, Mail, Moon, Sun, User } from "lucide-react"

import { BrandIcon } from "@/components/portfolio/brand-icons"
import { FloatingDock, FloatingDockItem, FloatingDockSeparator } from "@/components/portfolio/floating-dock"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { typography } from "@/lib/typography"

function DarkModeItem() {
  // Read the real mode after mount: `document` doesn't exist during server rendering.
  const [dark, setDark] = React.useState(false)
  React.useEffect(() => {
    queueMicrotask(() => setDark(document.documentElement.classList.contains("dark")))
  }, [])

  return (
    <FloatingDockItem
      label={dark ? "Light mode" : "Dark mode"}
      icon={dark ? <Sun /> : <Moon />}
      onClick={() => setDark(document.documentElement.classList.toggle("dark"))}
    />
  )
}

export default function FloatingDockDemo() {
  return (
    <>
      <main className="mx-auto flex max-w-3xl flex-col gap-10 px-5 pt-16 pb-40 sm:px-6 md:pt-24">
        <div className="flex flex-col gap-5">
          <p className={typography.eyebrow}>Design Engineer · Lisbon</p>
          <h1 className={typography.title}>I design and build calm, fast interfaces for ambitious product teams.</h1>
          <p className={typography.lead}>Hover the dock below, or Tab to it. It stays put while the page scrolls underneath.</p>
        </div>
        <div className="aspect-[16/10] overflow-hidden rounded-2xl border bg-muted">
          <GenerativeArt seed="dock-lumen" variant="interface" />
        </div>
        <div className="aspect-[16/10] overflow-hidden rounded-2xl border bg-muted">
          <GenerativeArt seed="dock-tidewater" variant="landscape" />
        </div>
      </main>
      <FloatingDock>
        <FloatingDockItem href="#home" label="Home" icon={<Home />} active />
        <FloatingDockItem href="#work" label="Work" icon={<Briefcase />} />
        <FloatingDockItem href="#about" label="About" icon={<User />} />
        <FloatingDockItem href="#writing" label="Writing" icon={<BookOpen />} />
        <FloatingDockSeparator />
        <FloatingDockItem href="https://github.com/example" label="GitHub" icon={<BrandIcon name="github" />} />
        <FloatingDockItem href="mailto:hello@example.com" label="Email" icon={<Mail />} />
        <FloatingDockSeparator />
        <DarkModeItem />
      </FloatingDock>
    </>
  )
}
```

### Inline

`position="static"` places the dock in the page flow, e.g. as a row of profile links under a bio or at the end of a page.

```tsx
import { Mail } from "lucide-react"

import { BrandIcon } from "@/components/portfolio/brand-icons"
import { FloatingDock, FloatingDockItem } from "@/components/portfolio/floating-dock"
import { typography } from "@/lib/typography"

const profiles = [
  { label: "GitHub", href: "https://github.com/example", brand: "github" },
  { label: "LinkedIn", href: "https://www.linkedin.com/in/example", brand: "linkedin" },
  { label: "Dribbble", href: "https://dribbble.com/example", brand: "dribbble" },
  { label: "Read.cv", href: "https://read.cv/example", brand: "readcv" },
] as const

export default function FloatingDockInline() {
  return (
    <div className="flex w-full max-w-md flex-col items-center gap-14 pt-6 text-center">
      <div className="flex flex-col gap-3">
        <p className={typography.eyebrow}>Elsewhere</p>
        <p className={typography.body}>Say hello, or find me where I post work in progress.</p>
      </div>
      <FloatingDock position="static" aria-label="Profiles" magnification={1.4}>
        {profiles.map((profile) => (
          <FloatingDockItem
            key={profile.label}
            href={profile.href}
            label={profile.label}
            icon={<BrandIcon name={profile.brand} />}
          />
        ))}
        <FloatingDockItem href="mailto:hello@example.com" label="Email" icon={<Mail />} />
      </FloatingDock>
    </div>
  )
}
```

## API Reference

### FloatingDock

The dock. `position="fixed"` (default) pins it to the bottom of the viewport, clear of the iOS home bar,
so leave room for it at the end of the page (bottom padding of about 6rem, and
`scroll-padding-bottom` so focused links don't end up underneath it). `position="static"` places it in
the flow. Magnification runs for a mouse or keyboard focus, never for touch or with reduced motion.
On touch screens items are 44px when they fit and shrink to fit the width when they don't.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `"fixed" \| "static"` | `"fixed"` | `fixed`: pinned to the bottom of the viewport, clear of the safe area (hidden in print). `static`: in the page flow, e.g. inside a footer or a demo. |
| `magnification` | `number` | `1.6` | Peak scale of the icon under the pointer (or with keyboard focus). `1` disables magnification. |
| `distance` | `number` | `140` | Pointer distance (px) over which neighbours are magnified. |

Also accepts every `nav` prop.

### FloatingDockItem

One icon: a link when `href` is set, otherwise a button (use `onClick` for actions like a theme switch).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` (required) | `React.ReactNode` | — | A lucide icon or `<BrandIcon>`; it scales with the item. |
| `label` (required) | `string` | — | Tooltip text and accessible name. |
| `active` | `boolean` | — | Adds a dot under the item: `aria-current="page"` on links (pass `aria-current="location"` for in-page sections), `aria-pressed` on buttons. |

Also accepts every `a` prop.

### FloatingDockSeparator

A thin divider between groups of items (pages · profiles · actions).

Also accepts every `li` prop.



---

# Footer Reveal

> The curtain footer: the page lifts away at the end to reveal the footer waiting underneath. Pure CSS sticky, with an optional lift-in effect.

Category: Layout · Registry item: `@portfolio-kit/footer-reveal` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/footer-reveal) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/footer-reveal.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/footer-reveal
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/footer-reveal.tsx` and the kit items it uses: `use-composed-refs`, `use-reduced-motion`.

## Usage

```tsx
import { SiteFooter } from "@/components/portfolio/site-footer"
import {
  FooterReveal,
  FooterRevealContent,
  FooterRevealFooter,
} from "@/components/portfolio/footer-reveal"

<FooterReveal>
  <FooterRevealContent>
    <main>…</main>
  </FooterRevealContent>
  <FooterRevealFooter>
    <SiteFooter>…</SiteFooter>
  </FooterRevealFooter>
</FooterReveal>
```

## Examples

### Demo

Scroll to the end: the page lifts like a curtain and the footer rises into place underneath it.

```tsx
import { FooterReveal, FooterRevealContent, FooterRevealFooter } from "@/components/portfolio/footer-reveal"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Section, SectionHeader, SectionTitle } from "@/components/portfolio/section"
import {
  SiteFooter,
  SiteFooterBottom,
  SiteFooterBrand,
  SiteFooterColumn,
  SiteFooterGrid,
  SiteFooterLink,
  SiteFooterWordmark,
} from "@/components/portfolio/site-footer"
import { typography } from "@/lib/typography"

const work = [
  { slug: "lumen", title: "Lumen", art: "interface" },
  { slug: "tidewater", title: "Tidewater", art: "interface" },
  { slug: "orbit", title: "Orbit", art: "interface" },
  { slug: "fieldnote", title: "Fieldnote", art: "bauhaus" },
] as const

export default function FooterRevealDemo() {
  return (
    <FooterReveal>
      <FooterRevealContent>
        <Section>
          <SectionHeader>
            <SectionTitle>Selected work</SectionTitle>
          </SectionHeader>
          <ul role="list" className="mt-10 grid gap-6 sm:grid-cols-2">
            {work.map((p) => (
              <li key={p.slug} className="flex flex-col gap-3">
                <div className="relative aspect-[4/3] overflow-hidden rounded-2xl border bg-muted">
                  <GenerativeArt seed={p.slug} variant={p.art} />
                </div>
                <a href={`#${p.slug}`} className="w-fit rounded-sm font-medium outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50">
                  {p.title}
                </a>
              </li>
            ))}
          </ul>
        </Section>
      </FooterRevealContent>
      <FooterRevealFooter>
        <SiteFooter className="border-t-0">
          <SiteFooterGrid>
            <SiteFooterBrand>
              <p className="font-heading text-2xl">Noa Vale</p>
              <p className={typography.body}>Calm, fast interfaces for ambitious teams.</p>
            </SiteFooterBrand>
            <SiteFooterColumn heading="Sitemap">
              <SiteFooterLink href="#work">Work</SiteFooterLink>
              <SiteFooterLink href="#about">About</SiteFooterLink>
              <SiteFooterLink href="#contact">Contact</SiteFooterLink>
            </SiteFooterColumn>
            <SiteFooterColumn heading="Elsewhere">
              <SiteFooterLink href="https://github.com/example" external>
                GitHub
              </SiteFooterLink>
              <SiteFooterLink href="https://example.com/rss.xml" external>
                RSS
              </SiteFooterLink>
            </SiteFooterColumn>
          </SiteFooterGrid>
          <SiteFooterBottom>
            <p>© 2026 Noa Vale</p>
            <a href="#top">Back to top</a>
          </SiteFooterBottom>
          <SiteFooterWordmark cut>Noa Vale</SiteFooterWordmark>
        </SiteFooter>
      </FooterRevealFooter>
    </FooterReveal>
  )
}
```

### Contact curtain

The last thing under the curtain is the invitation itself: a writer’s essay lifts away to reveal a contact block, with no lift effect so it reads calm.

```tsx
import { CopyEmail } from "@/components/portfolio/copy-email"
import {
  ContactCta,
  ContactCtaActions,
  ContactCtaAvailability,
  ContactCtaDescription,
  ContactCtaTitle,
} from "@/components/portfolio/contact-cta"
import { FooterReveal, FooterRevealContent, FooterRevealFooter } from "@/components/portfolio/footer-reveal"
import { Container } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

export default function FooterRevealContactCurtain() {
  return (
    <FooterReveal effect="none">
      <FooterRevealContent>
        <Container size="sm" className="flex flex-col gap-6 py-20 md:py-28">
          <p className={typography.eyebrow}>Essay · 9 min read</p>
          <h1 className={typography.title}>What a ferry timetable taught me about interfaces</h1>
          <p className={typography.lead}>
            Every crossing on the Skerry Line leaves on the minute, whatever the weather. For three months I tried to
            design software with the same promise: predictable, legible, and quietly on time.
          </p>
          <p className={typography.body}>
            The timetable never explains itself. It doesn’t need to. Columns line up, departures read top to bottom, and the
            one exception — a Sunday service that skips Fedje — is printed in the same weight as everything else. Nothing
            shouts, so the exception is easy to find.
          </p>
          <p className={typography.body}>
            Most of the interfaces I’ve shipped did the opposite: they explained, they decorated, they celebrated. The
            timetable just told you when to be at the pier.
          </p>
        </Container>
      </FooterRevealContent>
      <FooterRevealFooter>
        <ContactCta className="py-16 md:py-20">
          <ContactCtaAvailability detail="for essays and talks" />
          <ContactCtaTitle>Write back?</ContactCtaTitle>
          <ContactCtaDescription>Replies to essays are my favourite mail. I read every one, usually on the ferry.</ContactCtaDescription>
          <ContactCtaActions>
            <CopyEmail email="letters@example.com" variant="large" mailto />
          </ContactCtaActions>
        </ContactCta>
      </FooterRevealFooter>
    </FooterReveal>
  )
}
```

## API Reference

### FooterReveal

Wrap your page in it: a `<FooterRevealContent>` with everything above the footer, then a
`<FooterRevealFooter>` with your `<SiteFooter>`. The footer is `position: sticky` behind the
content, so the reveal needs no JavaScript. A footer taller than the screen scrolls normally,
and so does every footer under reduced motion and in print.

The footer stays after the content in the DOM, so keyboard and screen-reader order is the
reading order; a footer link that gets keyboard focus while still covered scrolls into view.
Same-page links to the footer or anything in it (`href="#contact"`) scroll to the end of the page,
where the footer is fully uncovered, and move focus there; this works with `SmoothScroll` too.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `effect` | `"none" \| "lift"` | `"lift"` | `lift`: the footer rises and scales up slightly as it's uncovered. `none`: it just sits there. Either way reduced motion gets the plain version. |

Also accepts every `div` prop.

### FooterRevealContent

Everything above the footer. It's the curtain: opaque, above the footer, with rounded bottom
corners and a soft shadow on its lower edge.

Also accepts every `div` prop.

### FooterRevealFooter

The footer's slot: sticks to the bottom of the viewport behind the content. Put your
`<SiteFooter>` (or anything) inside. Respects the bottom safe area on notched phones.

Also accepts every `div` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)



---

# Generative Art

> Deterministic SVG placeholder art from a seed string: product screenshots, landscapes and portraits, or abstract mesh, bauhaus, rings, waves and orb. Use it for covers, photos and avatars; it can take its colors from the theme.

Category: Utilities · Registry item: `@portfolio-kit/generative-art` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/generative-art) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/generative-art.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/generative-art
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/generative-art.tsx`.

## Usage

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
```

## Examples

### Demo

Placeholder covers, photos and portraits from any string — the same seed always draws the same artwork, so nothing shuffles between renders.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"

const tiles = [
  { seed: "lumen", variant: "interface", label: "Lumen — product screenshot" },
  { seed: "sintra", variant: "landscape", label: "Sintra — landscape photo" },
  { seed: "Noa Vale", variant: "portrait", label: "Noa Vale — portrait" },
] as const

export default function GenerativeArtDemo() {
  return (
    <div className="mx-auto grid w-full max-w-3xl grid-cols-2 gap-3 sm:grid-cols-[2fr_1.4fr_1fr]">
      {tiles.map((tile) => (
        <figure key={tile.seed} className="flex flex-col gap-2 last:max-sm:hidden">
          <div className="aspect-[3/4] overflow-hidden rounded-xl border shadow-card sm:aspect-auto sm:h-64">
            <GenerativeArt seed={tile.seed} variant={tile.variant} label={tile.label} />
          </div>
          <figcaption className="font-mono text-xs text-muted-foreground">{tile.variant}</figcaption>
        </figure>
      ))}
    </div>
  )
}
```

### Variants

Three stand-ins for real content — interface, landscape and portrait — and five abstract styles. Change the seed for a new palette and composition.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"

const variants = ["interface", "landscape", "portrait", "mesh", "bauhaus", "rings", "waves", "orb"] as const

export default function GenerativeArtVariants() {
  return (
    <div className="mx-auto grid max-w-5xl grid-cols-2 gap-4 md:grid-cols-4">
      {variants.map((variant) => (
        <figure key={variant} className="flex flex-col gap-2">
          <div className="aspect-[4/3] overflow-hidden rounded-xl border">
            <GenerativeArt seed={`kit-${variant}`} variant={variant} />
          </div>
          <figcaption className="font-mono text-xs text-muted-foreground">{variant}</figcaption>
        </figure>
      ))}
    </div>
  )
}
```

### Theme Tone

`tone="theme"` paints with your theme's highlight, primary and accent tokens, so the art re-colors with the theme and mode.

```tsx
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"

const tiles = [
  { seed: "notes", variant: "mesh", className: "col-span-2 row-span-2" },
  { seed: "index", variant: "bauhaus", className: "" },
  { seed: "signal", variant: "rings", className: "" },
  { seed: "tide", variant: "waves", className: "col-span-2" },
] as const

export default function GenerativeArtThemeTone() {
  return (
    <div className="mx-auto grid max-w-3xl auto-rows-[7rem] grid-cols-4 gap-3 sm:auto-rows-[9rem]">
      {tiles.map((tile) => (
        <div key={tile.seed} className={cn("overflow-hidden rounded-xl border", tile.className)}>
          <GenerativeArt seed={tile.seed} variant={tile.variant} tone="theme" />
        </div>
      ))}
    </div>
  )
}
```

### Avatar Fallbacks

Seed an orb with a person's name for a unique, stable avatar when there's no photo — `grain={false}` keeps tiny sizes clean.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"

const people = [
  { name: "Noa Vale", initials: "NV", role: "Design engineer" },
  { name: "Ines Carvalho", initials: "IC", role: "VP Product" },
  { name: "Sam Okafor", initials: "SO", role: "Ceramicist" },
]

export default function GenerativeArtAvatars() {
  return (
    <ul role="list" className="flex w-full max-w-xs flex-col gap-4">
      {people.map((person) => (
        <li key={person.name} className="flex items-center gap-3">
          <span className="relative flex size-11 shrink-0 items-center justify-center overflow-hidden rounded-full ring-1 ring-foreground/10">
            <GenerativeArt seed={person.name} variant="orb" grain={false} className="absolute inset-0 scale-[1.45]" />
            <span
              aria-hidden
              className="relative text-[0.8125rem] font-semibold tracking-wide text-white [text-shadow:0_1px_2px_rgb(0_0_0/0.5),0_0_10px_rgb(0_0_0/0.35)]"
            >
              {person.initials}
            </span>
          </span>
          <span className="flex min-w-0 flex-col">
            <span className="font-medium">{person.name}</span>
            <span className="text-sm text-muted-foreground">{person.role}</span>
          </span>
        </li>
      ))}
    </ul>
  )
}
```

## API Reference

### GenerativeArt

Fills its parent (`size-full`) with an SVG artwork drawn from `seed`. Put it inside a sized box
(an aspect-ratio frame, a card's media slot). Rendering is pure, so server and client output match.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `seed` (required) | `string` | — | Any string. The same seed always renders the same artwork. |
| `variant` | `"mesh" \| "bauhaus" \| "rings" \| "waves" \| "orb" \| "interface" \| "landscape" \| "portrait"` | `"mesh"` | Composition style. Stand-ins for real content: `interface` (a product screenshot — landing page, dashboard or gallery), `landscape` (a scenic photo) and `portrait` (a head-and-shoulders person). Abstract: soft `mesh` gradient, `bauhaus` tile grid, concentric `rings`, layered `waves` or a lit `orb`. |
| `tone` | `"seed" \| "theme"` | `"seed"` | `seed` derives a palette from the seed's hue; `theme` uses the active theme tokens (highlight, primary, accent, muted) so art re-colors with the theme. |
| `hue` | `number` | — | Override the seed-derived base hue (0–360). Only re-colors — the composition stays the same. |
| `label` | `string` | — | Accessible description. With a label the art is announced as an image (`role="img"`); use it when the art stands in for content, such as a project screenshot with no other description. Omit it (the default) for decoration or when a caption or title nearby already names the thing: the art is then `aria-hidden`. |
| `grain` | `boolean` | `true` | Overlay a subtle film-grain texture. Turn it off for tiny sizes (avatars, dots), and on pages with many large instances: each grain layer is a full-size SVG filter. |
| `as` | `"div" \| "span"` | `"div"` | Root element. Use `span` where only phrasing content is allowed, such as inside a `<button>` or a link; it renders as a block either way, so nothing changes visually. |

Also accepts every `div` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)
- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)
- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Links](https://www.parthjadhav.com/products/portfolio-kit/templates/links.md)
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)
- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Grain

> Film-grain noise overlay for the whole page or a single element, built from one cached SVG tile, with optional jitter and any blend mode.

Category: Effects · Registry item: `@portfolio-kit/grain` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/grain) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/grain.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/grain
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/grain.tsx`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { Grain, grainVariants } from "@/components/portfolio/grain"
```

## Examples

### Demo

One fixed noise layer over the whole page, with a brief jitter when it appears. Blended as an `overlay`, it textures the bold accent hero and leaves light surfaces clean. Render it once next to your layout.

```tsx
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Grain } from "@/components/portfolio/grain"
import { Section } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

const projects = [
  { slug: "lumen", title: "Lumen", year: 2025 },
  { slug: "tidewater", title: "Tidewater", year: 2025 },
  { slug: "fieldnote", title: "Fieldnote", year: 2024 },
] as const

export default function GrainDemo() {
  return (
    <main>
      {/* `overlay` keeps the noise in the mid-tones: it shows on the accent and leaves white cards clean. */}
      <Grain animated blend="overlay" opacity={0.3} frequency={0.65} />
      <div className="bg-highlight text-highlight-foreground">
        <Section spacing="sm" className="pt-16 md:pt-24">
          <p className={cn(typography.eyebrow, "text-highlight-foreground")}>Design Engineer · Lisbon</p>
          <h1 className={cn(typography.display, "mt-6 max-w-4xl")}>Interfaces with a little texture.</h1>
          <p className={cn(typography.lead, "mt-6 max-w-xl text-highlight-foreground")}>
            I design and build calm, fast interfaces for ambitious product teams.
          </p>
        </Section>
      </div>
      <Section spacing="sm">
        <ul role="list" className="grid gap-4 sm:grid-cols-3">
          {projects.map((project) => (
            <li key={project.slug} className="overflow-hidden rounded-2xl border bg-card shadow-card">
              <div className="aspect-[4/3] border-b">
                <GenerativeArt seed={project.slug} variant="interface" />
              </div>
              <div className="flex items-baseline justify-between gap-4 p-5">
                <h2 className={typography.heading}>{project.title}</h2>
                <span className={typography.meta}>{project.year}</span>
              </div>
            </li>
          ))}
        </ul>
      </Section>
    </main>
  )
}
```

### On an image

Scope grain to one cover with `position="absolute"`. An `overlay` blend keeps the noise in the mid-tones, like film.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Grain } from "@/components/portfolio/grain"

export default function GrainOnAnImage() {
  return (
    <figure className="relative isolate flex aspect-[4/5] w-full max-w-sm flex-col justify-end gap-1 overflow-hidden rounded-2xl p-6 text-white shadow-card md:p-8">
      <GenerativeArt seed="salt-flats" variant="landscape" className="absolute inset-0 -z-10" />
      <div aria-hidden className="absolute inset-0 -z-10 bg-gradient-to-t from-black/70 via-black/10 to-transparent" />
      <Grain position="absolute" opacity={0.2} blend="overlay" animated />
      <p className="relative z-20 font-mono text-xs tracking-[0.16em] text-white/75 uppercase">Portra 400 · Roll 12</p>
      <figcaption className="relative z-20 font-heading text-3xl md:text-4xl">Salt flats at dusk</figcaption>
    </figure>
  )
}
```

### Intensities

Film grain lives between 0.04 and 0.12 opacity; push past 0.2 only for deliberately gritty, poster-like surfaces. Same artwork, four strengths.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Grain } from "@/components/portfolio/grain"
import { typography } from "@/lib/typography"

const levels = [
  { opacity: 0.05, label: "Whisper" },
  { opacity: 0.1, label: "Film" },
  { opacity: 0.2, label: "Grit" },
  { opacity: 0.35, label: "Poster" },
]

export default function GrainIntensities() {
  return (
    <ul role="list" className="mx-auto grid max-w-4xl grid-cols-2 gap-4 md:grid-cols-4">
      {levels.map((level) => (
        <li key={level.opacity} className="flex flex-col gap-3">
          <div className="relative isolate aspect-square overflow-hidden rounded-xl border">
            <GenerativeArt seed="grain-swatch" variant="landscape" className="absolute inset-0 -z-10" />
            <Grain position="absolute" opacity={level.opacity} />
          </div>
          <div className="flex items-baseline justify-between gap-2">
            <span className="text-sm font-medium">{level.label}</span>
            <span className={typography.meta}>{level.opacity}</span>
          </div>
        </li>
      ))}
    </ul>
  )
}
```

## API Reference

### Grain

A decorative noise layer. It is `aria-hidden`, ignores the pointer and costs one
cached tile plus (when `animated`) a single stepped transform for 4.5 s. Hidden
in print and in forced-colors mode.

A `fixed` grain sits above the page, text included, so it lowers text contrast:
at the defaults (`0.08`, `normal`) grey text on white loses about a tenth of its
ratio, and an `overlay` at `0.3` costs coloured surfaces about as much. Keep text
under it well above 4.5:1, or texture only the surfaces: `position="absolute"`
inside the element, with the text above it (`relative z-20`, as on a cover).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `"fixed" \| "absolute"` | `"fixed"` | `fixed` covers the whole viewport above the page (`z-[100]`, never catches clicks); render it once. `absolute` fills the nearest positioned parent and inherits its corner radius; use it on a card or cover. |
| `opacity` | `number` | `0.08` | Layer opacity, 0–1. Film grain reads best between 0.04 and 0.12. |
| `animated` | `boolean` | `false` | Jitter the grain like projected film for a few seconds after it appears, then hold still. Off under reduced motion. |
| `blend` | `"normal" \| "overlay" \| "soft-light" \| "multiply" \| "screen" \| "difference"` | `"normal"` | CSS mix-blend-mode of the layer. `overlay`/`soft-light` only show on mid-tones. |
| `frequency` | `number` | `0.8` | Noise frequency. Higher is finer grain. |
| `size` | `number` | `180` | Tile size in px. The noise is rasterized once at this size and repeated. |

Also accepts every `div` prop.



---

# Hero Intro

> The main portfolio hero: eyebrow, display title, lead, actions, optional media and a bottom meta row, with a staggered CSS entrance. Stacked, split or centered.

Category: Hero · Registry item: `@portfolio-kit/hero-intro` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/hero-intro) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/hero-intro.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/hero-intro
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/hero-intro.tsx` and the kit items it uses: `section`, `typography`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  HeroIntro,
  HeroIntroActions,
  HeroIntroContent,
  HeroIntroDescription,
  HeroIntroEyebrow,
  HeroIntroMedia,
  HeroIntroTitle,
} from "@/components/portfolio/hero-intro"

<HeroIntro>
  <HeroIntroContent>
    <HeroIntroEyebrow>Design engineer in Lisbon</HeroIntroEyebrow>
    <HeroIntroTitle>I build calm, fast interfaces for product teams.</HeroIntroTitle>
    <HeroIntroDescription>Nine years turning rough ideas into software people enjoy.</HeroIntroDescription>
    <HeroIntroActions>
      <a href="#work">Selected work</a>
    </HeroIntroActions>
  </HeroIntroContent>
  <HeroIntroMedia>
    <img src="/portrait.jpg" alt="Portrait" />
  </HeroIntroMedia>
</HeroIntro>
```

## Examples

### Demo

A status badge, a headline with a rotating word, a short lead and two actions, entering one after another.

```tsx
import { ArrowRight } from "lucide-react"

import { cn } from "@/lib/utils"
import { buttonVariants } from "@/components/ui/button"
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import {
  HeroIntro,
  HeroIntroActions,
  HeroIntroContent,
  HeroIntroDescription,
  HeroIntroEyebrow,
  HeroIntroTitle,
} from "@/components/portfolio/hero-intro"
import { WordRotate } from "@/components/portfolio/word-rotate"

export default function HeroIntroDemo() {
  return (
    <HeroIntro>
      <HeroIntroContent>
        <HeroIntroEyebrow>
          <AvailabilityBadge detail="from November">Available</AvailabilityBadge>
        </HeroIntroEyebrow>
        <HeroIntroTitle>
          I build <WordRotate words={["interfaces", "systems", "tools", "prototypes"]} tone="highlight" /> for
          ambitious product teams.
        </HeroIntroTitle>
        <HeroIntroDescription>
          Noa Vale is a design engineer in Lisbon — nine years turning rough ideas into calm, fast software. Currently
          leading the design system at Halcyon Labs.
        </HeroIntroDescription>
        <HeroIntroActions>
          <a href="#work" className={cn(buttonVariants({ size: "lg" }), "h-11 rounded-pill px-6")}>
            Selected work <ArrowRight aria-hidden />
          </a>
          <a
            href="mailto:hello@example.com"
            className={cn(buttonVariants({ variant: "outline", size: "lg" }), "h-11 rounded-pill px-6")}
          >
            Get in touch
          </a>
        </HeroIntroActions>
      </HeroIntroContent>
    </HeroIntro>
  )
}
```

### Split

`layout="split"` puts copy on the left and a portrait or visual on the right; on phones the media stacks underneath.

```tsx
import { cn } from "@/lib/utils"
import { buttonVariants } from "@/components/ui/button"
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  HeroIntro,
  HeroIntroActions,
  HeroIntroContent,
  HeroIntroDescription,
  HeroIntroEyebrow,
  HeroIntroMedia,
  HeroIntroTitle,
} from "@/components/portfolio/hero-intro"
import { typography } from "@/lib/typography"

export default function HeroIntroSplit() {
  return (
    <HeroIntro layout="split">
      <HeroIntroContent>
        <HeroIntroEyebrow className={typography.eyebrow}>Independent designer — Lisbon</HeroIntroEyebrow>
        <HeroIntroTitle>Brands and interfaces with a quiet kind of confidence.</HeroIntroTitle>
        <HeroIntroDescription>
          I partner with founders and small studios on identity, product and the space between. Now booking projects
          for early next year.
        </HeroIntroDescription>
        <HeroIntroActions className="gap-6">
          <a href="#work" className={cn(buttonVariants({ size: "lg" }), "h-11 rounded-pill px-6")}>
            View projects
          </a>
          <ArrowLink href="#about" tone="muted">
            About me
          </ArrowLink>
        </HeroIntroActions>
      </HeroIntroContent>
      <HeroIntroMedia>
        <GenerativeArt seed="studio-portrait" variant="portrait" label="Portrait of Noa in the studio" />
        <span className="absolute bottom-3 left-3 rounded-pill bg-black/45 px-2.5 py-1 font-mono text-[0.6875rem] tracking-wide text-white backdrop-blur-sm">
          Studio, 2025
        </span>
      </HeroIntroMedia>
    </HeroIntro>
  )
}
```

### Centered

`layout="center"` for personal, link-in-bio style pages: an avatar, a short hello, and socials beside the main action.

```tsx
import { cn } from "@/lib/utils"
import { buttonVariants } from "@/components/ui/button"
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  HeroIntro,
  HeroIntroActions,
  HeroIntroContent,
  HeroIntroDescription,
  HeroIntroEyebrow,
  HeroIntroTitle,
} from "@/components/portfolio/hero-intro"
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"

const socials = ["https://github.com/example", "https://x.com/example", "https://www.linkedin.com/in/example"]

export default function HeroIntroCentered() {
  return (
    <HeroIntro layout="center">
      <HeroIntroContent>
        <HeroIntroEyebrow className="flex-col gap-4">
          <span className="relative size-20 overflow-hidden rounded-full ring-1 ring-foreground/10">
            <GenerativeArt seed="Noa Vale" variant="portrait" label="Portrait of Noa" />
          </span>
          <AvailabilityBadge variant="soft" />
        </HeroIntroEyebrow>
        <HeroIntroTitle>Hi, I&rsquo;m Noa.</HeroIntroTitle>
        <HeroIntroDescription>I design and build calm, fast interfaces for ambitious product teams.</HeroIntroDescription>
        <HeroIntroActions>
          <a href="mailto:hello@example.com" className={cn(buttonVariants({ size: "lg" }), "h-11 rounded-pill px-6")}>
            Say hello
          </a>
          <SocialLinks>
            {socials.map((href) => (
              <SocialLink key={href} href={href} />
            ))}
          </SocialLinks>
        </HeroIntroActions>
      </HeroIntroContent>
    </HeroIntro>
  )
}
```

### Full Height

`fullHeight` fills the viewport and anchors the statement to the bottom, above a meta row with location, local time and a scroll cue.

```tsx
import {
  HeroIntro,
  HeroIntroContent,
  HeroIntroEyebrow,
  HeroIntroFooter,
  HeroIntroTitle,
} from "@/components/portfolio/hero-intro"
import { LocalTime } from "@/components/portfolio/local-time"
import { LocationTag } from "@/components/portfolio/location-tag"
import { ScrollCue } from "@/components/portfolio/scroll-cue"
import { Section, SectionEyebrow, SectionHeader, SectionTitle } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

export default function HeroIntroFullHeight() {
  return (
    <>
      <HeroIntro fullHeight>
        <HeroIntroContent>
          <HeroIntroEyebrow>
            <span className={typography.eyebrow}>Design engineer</span>
          </HeroIntroEyebrow>
          <HeroIntroTitle className="max-w-6xl">Noa Vale designs and builds calm, fast interfaces.</HeroIntroTitle>
        </HeroIntroContent>
        <HeroIntroFooter>
          <LocationTag location="Lisbon, Portugal" />
          <LocalTime timeZone="Europe/Lisbon" className="max-md:hidden" />
          <ScrollCue href="#work" layout="inline" variant="line" />
        </HeroIntroFooter>
      </HeroIntro>
      <Section id="work">
        <SectionHeader>
          <SectionEyebrow index={1}>Selected work</SectionEyebrow>
          <SectionTitle>Things I&rsquo;ve shipped lately</SectionTitle>
        </SectionHeader>
      </Section>
    </>
  )
}
```

## API Reference

### HeroIntro

The page's opening section. Compose `HeroIntroContent` (eyebrow, title, description,
actions), an optional `HeroIntroMedia` and an optional `HeroIntroFooter` inside it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `layout` | `"stack" \| "split" \| "center"` | `"stack"` | `stack`: one left-aligned column, media full width below. `split`: copy on the left, `HeroIntroMedia` on the right (stacks on phones). `center`: a centered column for personal, link-in-bio style pages. |
| `fullHeight` | `boolean` | `false` | Fill the viewport (`100svh`) and anchor the content to the bottom, above `HeroIntroFooter`. |
| `size` | `"sm" \| "default" \| "lg" \| "full"` | `"lg"` | Container width (see `Container`). |
| `animate` | `boolean` | `true` | Play the staggered entrance. It is pure CSS, so content shows without JavaScript and in print, and it is always off when the user prefers reduced motion. |
| `delay` | `number` | `0` | Delay before the first part enters, in ms. |
| `stagger` | `number` | `80` | Delay between parts, in ms. |

Also accepts every `section` prop.

### HeroIntroContent

Column holding the eyebrow, title, description and actions.

Also accepts every `div` prop.

### HeroIntroEyebrow

Small row above the title for availability, local time or a label.

Also accepts every `div` prop.

### HeroIntroTitle

Display-size statement: your name, role or promise. Renders the page's `h1` by default; set `as`
when the page already has one. Lines are balanced (`text-balance`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h1" \| "h2" \| "p"` | `"h1"` | Heading level. Keep `h1` unless the page already has one. |

Also accepts every `h1` prop.

### HeroIntroDescription

Lead paragraph under the title, one or two sentences.

Also accepts every `p` prop.

### HeroIntroActions

Row of buttons and links (style `<a>` elements with `buttonVariants`).

Also accepts every `div` prop.

### HeroIntroMedia

Portrait or visual. Right column in `split`, full width below the content in `stack` and `center`.
The box keeps a fixed aspect ratio (4:5 in `split`, 16:10 then 21:9 in `stack`, 16:9 in `center`),
so nothing shifts while an image loads; change it with an `aspect-*` class. A direct `<img>` child
fills and crops it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hideOnMobile` | `boolean` | `false` | Hide below `md` instead of stacking under the content. |

Also accepts every `div` prop.

### HeroIntroFooter

Bottom meta row (location · local time · scroll cue), set off by a rule.

Also accepts every `div` prop.

## Used in templates

- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)



---

# Hero Statement

> Oversized typographic hero. Lines slide up from a mask, inline media pills widen on hover, and a labeled meta grid sits underneath.

Category: Hero · Registry item: `@portfolio-kit/hero-statement` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/hero-statement) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/hero-statement.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/hero-statement
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/hero-statement.tsx` and the kit items it uses: `section`, `typography`.

## Usage

```tsx
import {
  HeroStatement,
  HeroStatementHeading,
  HeroStatementInline,
  HeroStatementLine,
  HeroStatementMeta,
  HeroStatementMetaItem,
} from "@/components/portfolio/hero-statement"

<HeroStatement>
  <HeroStatementHeading>
    <HeroStatementLine>
      Designing{" "}
      <HeroStatementInline>
        <img src="/studio.jpg" alt="" />
      </HeroStatementInline>{" "}
      calm software
    </HeroStatementLine>
    <HeroStatementLine>for ambitious teams.</HeroStatementLine>
  </HeroStatementHeading>
  <HeroStatementMeta>
    <HeroStatementMetaItem label="Currently">Design engineer, Halcyon Labs</HeroStatementMetaItem>
    <HeroStatementMetaItem label="Based in">Lisbon, Portugal</HeroStatementMetaItem>
  </HeroStatementMeta>
</HeroStatement>
```

## Examples

### Demo

An oversized, line-by-line typographic hero with inline artwork pills that widen on hover, and a labelled meta grid underneath.

```tsx
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  HeroStatement,
  HeroStatementHeading,
  HeroStatementInline,
  HeroStatementLine,
  HeroStatementMeta,
  HeroStatementMetaItem,
} from "@/components/portfolio/hero-statement"
import { LocalTime } from "@/components/portfolio/local-time"

export default function HeroStatementDemo() {
  return (
    <HeroStatement>
      <HeroStatementHeading>
        <HeroStatementLine>
          Designing{" "}
          <HeroStatementInline>
            <GenerativeArt seed="statement-1" variant="interface" />
          </HeroStatementInline>{" "}
          calm
        </HeroStatementLine>
        <HeroStatementLine className="md:pl-[1.2em]">
          software for{" "}
          <HeroStatementInline width="1.4em" expandedWidth="2.2em">
            <GenerativeArt seed="statement-2" variant="portrait" />
          </HeroStatementInline>
        </HeroStatementLine>
        <HeroStatementLine className="text-muted-foreground">ambitious teams.</HeroStatementLine>
      </HeroStatementHeading>
      <HeroStatementMeta>
        <HeroStatementMetaItem label="Currently">Staff design engineer, Halcyon Labs</HeroStatementMetaItem>
        <HeroStatementMetaItem label="Based in">
          Lisbon, Portugal
          <LocalTime timeZone="Europe/Lisbon" city={false} className="mt-1 flex text-xs text-muted-foreground" />
        </HeroStatementMetaItem>
        <HeroStatementMetaItem label="Focus">Design systems, motion, prototyping</HeroStatementMetaItem>
        <HeroStatementMetaItem label="Status">
          <AvailabilityBadge variant="plain" className="md:text-base">
            Taking projects
          </AvailabilityBadge>
        </HeroStatementMetaItem>
      </HeroStatementMeta>
    </HeroStatement>
  )
}
```

### Centered Studio

Centered lines with an italic word and artwork pills. Suits studios and editorial portfolios, especially with a serif theme.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  HeroStatement,
  HeroStatementHeading,
  HeroStatementInline,
  HeroStatementLine,
  HeroStatementMeta,
  HeroStatementMetaItem,
} from "@/components/portfolio/hero-statement"

export default function HeroStatementEditorial() {
  return (
    <HeroStatement>
      <HeroStatementHeading className="text-center">
        <HeroStatementLine>
          <em>Studio</em> for{" "}
          <HeroStatementInline width="2em" expandedWidth="3em">
            <GenerativeArt seed="rings-editorial" variant="bauhaus" />
          </HeroStatementInline>
        </HeroStatementLine>
        <HeroStatementLine>identity &amp;</HeroStatementLine>
        <HeroStatementLine>
          <HeroStatementInline>
            <GenerativeArt seed="studio-interfaces" variant="interface" />
          </HeroStatementInline>{" "}
          interfaces
        </HeroStatementLine>
      </HeroStatementHeading>
      <HeroStatementMeta className="md:grid-cols-3">
        <HeroStatementMetaItem label="Est.">2019, Lisbon</HeroStatementMetaItem>
        <HeroStatementMetaItem label="Clients">Halcyon, Tidewater, Fieldnote, Orbit</HeroStatementMetaItem>
        <HeroStatementMetaItem label="Contact">
          <a
            href="mailto:studio@example.com"
            className="rounded-sm underline decoration-foreground/30 underline-offset-4 outline-none transition-colors duration-200 ease-smooth hover:decoration-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50"
          >
            studio@example.com
          </a>
        </HeroStatementMetaItem>
      </HeroStatementMeta>
    </HeroStatement>
  )
}
```

### Text Only

Just the lines, with no pills or meta grid. At this size, two short lines are enough.

```tsx
import {
  HeroStatement,
  HeroStatementHeading,
  HeroStatementLine,
} from "@/components/portfolio/hero-statement"

export default function HeroStatementTextOnly() {
  return (
    <HeroStatement>
      <HeroStatementHeading>
        <HeroStatementLine>Less, but</HeroStatementLine>
        <HeroStatementLine className="text-highlight-ink">considered.</HeroStatementLine>
      </HeroStatementHeading>
    </HeroStatement>
  )
}
```

## API Reference

### HeroStatement

Section wrapper. Put a `HeroStatementHeading` (made of `HeroStatementLine`s) and an optional
`HeroStatementMeta` grid inside. Other content, like an eyebrow above the heading, works too.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg" \| "full"` | `"lg"` | Container width (see `Container`). |
| `animate` | `boolean` | `true` | Play the line-by-line entrance. Always off when the user prefers reduced motion. |
| `delay` | `number` | `0` | Delay before the first line, in ms. |
| `stagger` | `number` | `90` | Delay between lines, in ms. |

Also accepts every `section` prop.

### HeroStatementHeading

The statement itself. Each direct child is a `HeroStatementLine`; they enter in order. Its size
(48 px up to 144 px, 9vw between) follows the theme's `--display-scale`, like `typography.display`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h1" \| "h2" \| "p"` | `"h1"` | Heading level. Keep `h1` unless the page already has one. |

Also accepts every `h1` prop.

### HeroStatementLine

One line of the statement. It slides up from its own mask. Inline pills stay glued to the
word before them (or after them, when a pill opens the line). Lines are separated by a space
in the text, so screen readers, search and copy read "calm software", not "calmsoftware".

Also accepts every `span` prop.

### HeroStatementInline

Inline media pill between words: artwork or an image, sitting on the baseline and as tall as
the font's capitals. Widens on hover (not with reduced motion). As a direct child of
`HeroStatementLine` it is glued to the word before it, so it never wraps alone.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `string` | `"1.7em"` | Resting width (any CSS length; `em` scales with the type). |
| `expandedWidth` | `string` | `"2.6em"` | Width on hover. |
| `label` | `string` | — | Accessible description of the media. It becomes part of the heading's accessible name, so omit it (the default, decorative) unless the image carries meaning. |

Also accepts every `span` prop.

### HeroStatementMeta

Grid of small labeled columns under the statement: "Currently", "Based in", "Focus"…

Also accepts every `dl` prop.

### HeroStatementMetaItem

One labeled column of the meta grid: a `<dt>` label over a `<dd>` value (children).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `React.ReactNode` | — | Small uppercase term above the value, e.g. "Currently" or "Based in". |

Also accepts every `div` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Hero Video

> A full-bleed hero over a muted, looping background video, with a legible scrim and a visible pause button; it shows the poster under reduced motion or Save-Data and rests while off screen.

Category: Hero · Registry item: `@portfolio-kit/hero-video` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/hero-video) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/hero-video.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/hero-video
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/hero-video.tsx` and the kit items it uses: `section`, `typography`, `use-composed-refs`, `use-in-view`, `use-page-visible`, `use-reduced-motion`, `use-save-data`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  HeroVideo,
  HeroVideoActions,
  HeroVideoContent,
  HeroVideoControls,
  HeroVideoDescription,
  HeroVideoEyebrow,
  HeroVideoPoster,
  HeroVideoTitle,
} from "@/components/portfolio/hero-video"

<HeroVideo src="/hero.mp4" scrim="bottom">
  <HeroVideoPoster>
    <img src="/hero-poster.jpg" alt="" />
  </HeroVideoPoster>
  <HeroVideoContent>
    <HeroVideoEyebrow>Director and cinematographer</HeroVideoEyebrow>
    <HeroVideoTitle>Films from the edge of the Atlantic.</HeroVideoTitle>
    <HeroVideoDescription>Documentary and brand work, shot on location since 2014.</HeroVideoDescription>
    <HeroVideoActions>
      <a href="#work">Watch the work</a>
    </HeroVideoActions>
  </HeroVideoContent>
  <HeroVideoControls />
</HeroVideo>
```

## Examples

### Demo

A filmmaker’s opening screen: a muted clip loops behind the name and a short promise, over a bottom scrim, with the pause button in the corner.

```tsx
import { ArrowRight } from "lucide-react"

import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  HeroVideo,
  HeroVideoActions,
  HeroVideoContent,
  HeroVideoDescription,
  HeroVideoEyebrow,
  HeroVideoPoster,
  HeroVideoTitle,
} from "@/components/portfolio/hero-video"

export default function HeroVideoDemo() {
  return (
    // Your clip: a file in public/ ("/hero.mp4") or a CDN URL. The demo clip sits next to the docs preview.
    <HeroVideo src="media/showreel.mp4">
      <HeroVideoPoster>
        <GenerativeArt seed="atlantic-coast" variant="landscape" />
      </HeroVideoPoster>
      <HeroVideoContent>
        <HeroVideoEyebrow>Ines Morrow · Director and cinematographer</HeroVideoEyebrow>
        <HeroVideoTitle>Films from the edge of the Atlantic.</HeroVideoTitle>
        <HeroVideoDescription>
          Documentary and brand films shot on location, from the Azores to the Faroe Islands, since 2014.
        </HeroVideoDescription>
        <HeroVideoActions>
          <a href="#work" className={cn(buttonVariants({ size: "lg" }), "h-11 rounded-pill px-6")}>
            Watch the work <ArrowRight aria-hidden />
          </a>
          <a
            href="mailto:ines@example.com"
            className={cn(buttonVariants({ variant: "outline", size: "lg" }), "h-11 rounded-pill px-6")}
          >
            Get in touch
          </a>
        </HeroVideoActions>
      </HeroVideoContent>
    </HeroVideo>
  )
}
```

### With Scroll Cue

A photographer’s landing: just the name and the year’s project at the bottom, a scroll cue linking to the work, and the pause button beside it.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  HeroVideo,
  HeroVideoContent,
  HeroVideoControls,
  HeroVideoEyebrow,
  HeroVideoPoster,
  HeroVideoTitle,
} from "@/components/portfolio/hero-video"
import { ScrollCue } from "@/components/portfolio/scroll-cue"
import { Section, SectionEyebrow, SectionHeader, SectionTitle } from "@/components/portfolio/section"

export default function HeroVideoScrollCue() {
  return (
    <>
      <HeroVideo src="media/showreel.mp4" size="full">
        <HeroVideoPoster>
          <GenerativeArt seed="northern-light" variant="landscape" />
        </HeroVideoPoster>
        <HeroVideoContent className="max-w-none">
          <HeroVideoEyebrow>Now showing · Northern Light, 2026</HeroVideoEyebrow>
          <HeroVideoTitle>Tomas Lind</HeroVideoTitle>
        </HeroVideoContent>
        {/* Your own controls row: the scroll cue sits next to the pause button. */}
        <HeroVideoControls className="gap-6">
          <ScrollCue href="#series" layout="inline" variant="line" tone="on-media" />
        </HeroVideoControls>
      </HeroVideo>
      <Section id="series">
        <SectionHeader>
          <SectionEyebrow index={1}>Series</SectionEyebrow>
          <SectionTitle>Five winters above the Arctic Circle</SectionTitle>
        </SectionHeader>
      </Section>
    </>
  )
}
```

### Inset

A shorter, rounded video band inside the page column with centered copy on a full scrim, for a studio page that opens with a header above it.

```tsx
import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  HeroVideo,
  HeroVideoActions,
  HeroVideoContent,
  HeroVideoDescription,
  HeroVideoPoster,
  HeroVideoTitle,
} from "@/components/portfolio/hero-video"
import { Container } from "@/components/portfolio/section"

export default function HeroVideoInset() {
  return (
    <Container className="py-6 md:py-10">
      <HeroVideo
        src="media/showreel.mp4"
        fullHeight={false}
        align="center"
        scrim="full"
        size="sm"
        className="rounded-2xl border shadow-card"
      >
        <HeroVideoPoster>
          <GenerativeArt seed="harbour-studio" variant="landscape" />
        </HeroVideoPoster>
        <HeroVideoContent>
          <HeroVideoTitle className="md:text-7xl lg:text-7xl">Harbour Studio</HeroVideoTitle>
          <HeroVideoDescription>A small motion and film studio in Porto. Title sequences, product films, identities.</HeroVideoDescription>
          <HeroVideoActions>
            <a href="#reel" className={cn(buttonVariants({ size: "lg" }), "h-11 rounded-pill px-6")}>
              See the reel
            </a>
          </HeroVideoActions>
        </HeroVideoContent>
      </HeroVideo>
    </Container>
  )
}
```

## API Reference

### HeroVideo

The hero section. The video, poster and scrim fill it; `HeroVideoContent` holds the copy. A pause
button is added automatically (WCAG 2.2.2) unless you place a `HeroVideoControls` yourself. The video
also rests while the hero is off screen or the tab is hidden.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | — | Video URL (MP4/WebM). Short, silent, small and seamless works best: it plays muted and loops. |
| `sources` | `HeroVideoSource[]` | — | Several encodings, in order of preference (e.g. WebM, then MP4). Used instead of `src`. |
| `poster` | `string` | — | Poster image URL, shown until the first frame plays and whenever the video doesn't run (reduced motion, Save-Data). For artwork (`<GenerativeArt />`, `<picture>`), use `HeroVideoPoster` instead. |
| `scrim` | `"none" \| "bottom" \| "full"` | `"bottom"` | Darkening over the video that keeps the text readable. `bottom`: a gradient under bottom-aligned copy. `full`: an even layer for centered copy. `none`: bring your own (or a very dark clip). No scrim suits every clip: check your text over the lightest frames (and the poster), and darken it for bright footage with `className="[&>[data-slot=hero-video-scrim]]:bg-black/70"`. |
| `align` | `"bottom" \| "center"` | `"bottom"` | `bottom` anchors the copy to the bottom-left; `center` centers it. |
| `fullHeight` | `boolean` | `true` | Fill the viewport (`100dvh`). Off: a shorter band (32rem, 40rem from `md`). |
| `size` | `"sm" \| "default" \| "lg" \| "full"` | `"lg"` | Container width for the copy (see `Container`). |
| `paused` | `boolean` | — | Controlled paused state. |
| `defaultPaused` | `boolean` | `false` | Initial paused state when uncontrolled. The video also starts paused (showing the poster) when the user prefers reduced motion or reduced data, until they press play. |
| `onPausedChange` | `(paused: boolean) => void` | — | Called when the visitor presses pause or play. |

Also accepts every `section` prop.

### HeroVideoPoster

Artwork under the video: an `<img>` or `<picture>` (cropped to fill) or `<GenerativeArt />`. It shows
until the first frame plays, and stays when the video doesn't run. Must be a **direct** child.

Also accepts every `div` prop.

### HeroVideoContent

Column for the eyebrow, title, description and actions, over the scrim.

Also accepts every `div` prop.

### HeroVideoEyebrow

Small mono label above the title: your role, place or the clip's credit.

Also accepts every `p` prop.

### HeroVideoTitle

Display-size headline (`h1`), or one step smaller as an `h2`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h1" \| "h2" \| "p"` | `"h1"` | Heading level. Keep `h1` unless the page already has one. An `h2` (a reel band below the page's hero) is set one step smaller at every width, so it never outsizes the page's `h1`. |

Also accepts every `h1` prop.

### HeroVideoDescription

Lead paragraph under the title, one or two sentences.

Also accepts every `p` prop.

### HeroVideoActions

Row of buttons and links (style `<a>` elements with `buttonVariants`).

Also accepts every `div` prop.

### HeroVideoControls

The pause button, pinned to the bottom-right corner (inside the safe area). `HeroVideo` adds one for
you; place it yourself to change its label or position (`className`), or to add controls beside it.
Keep it visible: motion that starts on its own and lasts more than five seconds needs a way to pause
it (WCAG 2.2.2). Hidden when there is no playable video, and in print.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Pause background video"` | Accessible name of the pause button. It stays the same; `aria-pressed` announces the state. |

Also accepts every `div` prop.

### type HeroVideoSource

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `src` (required) | `string` | — | File URL. |
| `type` | `string` | — | MIME type, e.g. `video/webm` or `video/mp4`. Lets the browser skip formats it can't play. |

## Used in templates

- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Horizontal Scroll

> A pinned section whose row of cards travels sideways as you scroll down, with a progress bar. On touch screens, small or short viewports, reduced motion and in print it's a native swipeable row with snap points.

Category: Effects · Registry item: `@portfolio-kit/horizontal-scroll` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/horizontal-scroll) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/horizontal-scroll.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/horizontal-scroll
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/horizontal-scroll.tsx` and the kit items it uses: `use-composed-refs`, `use-fine-pointer`, `use-media-query`, `use-reduced-motion`.

## Usage

```tsx
import {
  ProjectCard,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import {
  HorizontalScroll,
  HorizontalScrollHeader,
  HorizontalScrollItem,
  HorizontalScrollProgress,
  HorizontalScrollTrack,
} from "@/components/portfolio/horizontal-scroll"

<HorizontalScroll>
  <HorizontalScrollHeader>
    <h2>Selected work</h2>
  </HorizontalScrollHeader>
  <HorizontalScrollTrack label="Selected work">
    <HorizontalScrollItem>
      <ProjectCard href="/work/lumen">
        <ProjectCardTitle>Lumen</ProjectCardTitle>
      </ProjectCard>
    </HorizontalScrollItem>
    <HorizontalScrollItem>
      <ProjectCard href="/work/tidewater">
        <ProjectCardTitle>Tidewater</ProjectCardTitle>
      </ProjectCard>
    </HorizontalScrollItem>
  </HorizontalScrollTrack>
  <HorizontalScrollProgress />
</HorizontalScroll>
```

## Examples

### Demo

Selected work that travels sideways while the section is pinned. Try it with a mouse, then on a phone: it becomes a swipeable row.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  HorizontalScroll,
  HorizontalScrollHeader,
  HorizontalScrollItem,
  HorizontalScrollProgress,
  HorizontalScrollTrack,
} from "@/components/portfolio/horizontal-scroll"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import { typography } from "@/lib/typography"

const projects = [
  { title: "Lumen", client: "Halcyon Labs", year: "2026", seed: "lumen" },
  { title: "Northwind Rail", client: "Northwind", year: "2025", seed: "northwind" },
  { title: "Field Notes", client: "Moss & Co", year: "2025", seed: "field-notes" },
  { title: "Tidewater", client: "Coastal Trust", year: "2024", seed: "tidewater" },
  { title: "Paper City", client: "Atlas Press", year: "2024", seed: "paper-city" },
] as const

export default function HorizontalScrollDemo() {
  return (
    <main>
      <HorizontalScroll className="border-b">
        <HorizontalScrollHeader>
          <div className="flex flex-col gap-3">
            <p className={typography.eyebrow}>Selected work</p>
            <h2 className={typography.title}>Five years, five projects</h2>
          </div>
          <p className={typography.meta}>Scroll to explore · 2024 — 2026</p>
        </HorizontalScrollHeader>
        <HorizontalScrollTrack label="Selected work">
          {projects.map((project) => (
            <HorizontalScrollItem key={project.seed}>
              <ProjectCard href={`#${project.seed}`}>
                <ProjectCardMedia>
                  <GenerativeArt seed={project.seed} variant="interface" />
                </ProjectCardMedia>
                <ProjectCardContent>
                  <ProjectCardMeta>
                    <span>{project.year}</span>
                    <span>{project.client}</span>
                  </ProjectCardMeta>
                  <ProjectCardTitle>{project.title}</ProjectCardTitle>
                </ProjectCardContent>
              </ProjectCard>
            </HorizontalScrollItem>
          ))}
        </HorizontalScrollTrack>
        <HorizontalScrollProgress />
      </HorizontalScroll>

      <section className="mx-auto flex min-h-[420px] max-w-6xl items-center px-5 sm:px-6 md:px-8">
        <p className={`${typography.lead} max-w-md`}>Once the last card is in view, the page carries on scrolling as normal.</p>
      </section>
    </main>
  )
}
```

### Photo Series

A photographer’s series as a sideways filmstrip: portrait and landscape frames share one height, each with a numbered caption.

```tsx
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  HorizontalScroll,
  HorizontalScrollHeader,
  HorizontalScrollItem,
  HorizontalScrollProgress,
  HorizontalScrollTrack,
} from "@/components/portfolio/horizontal-scroll"
import { typography } from "@/lib/typography"

/** Widths chosen so a 3:2 landscape and a 4:5 portrait come out the same height at every breakpoint. */
const frame = {
  landscape: { item: "w-[80vw] sm:w-[27rem] lg:w-[33rem]", media: "aspect-[3/2]" },
  portrait: { item: "w-[42.7vw] sm:w-[14.4rem] lg:w-[17.6rem]", media: "aspect-[4/5]" },
}

const photos = [
  { seed: "coast-porto", caption: "Porto, first light", orientation: "landscape", variant: "landscape" },
  { seed: "coast-nazare", caption: "Nazaré, the north beach", orientation: "portrait", variant: "portrait" },
  { seed: "coast-sagres", caption: "Sagres, off-season", orientation: "landscape", variant: "landscape" },
  { seed: "coast-ericeira", caption: "Ericeira, low tide", orientation: "portrait", variant: "portrait" },
  { seed: "coast-comporta", caption: "Comporta, rice fields", orientation: "landscape", variant: "landscape" },
] as const

export default function HorizontalScrollPhotoSeries() {
  return (
    <main>
      <HorizontalScroll className="border-b">
        <HorizontalScrollHeader>
          <div className="flex flex-col gap-3">
            <p className={typography.eyebrow}>Series · 2023 — 2025</p>
            <h2 className={typography.title}>Coastlines</h2>
          </div>
          <p className={typography.meta}>{photos.length} frames · 35mm film</p>
        </HorizontalScrollHeader>
        <HorizontalScrollTrack label="Coastlines series" className="items-start">
          {photos.map((photo, i) => (
            <HorizontalScrollItem key={photo.seed} className={frame[photo.orientation].item}>
              <figure className="flex flex-col gap-3">
                <div className={cn("overflow-hidden rounded-md bg-muted", frame[photo.orientation].media)}>
                  <GenerativeArt seed={photo.seed} variant={photo.variant} label={photo.caption} />
                </div>
                <figcaption className={cn(typography.meta, "flex gap-3")}>
                  <span className="text-highlight-ink">{String(i + 1).padStart(2, "0")}</span>
                  <span className="truncate">{photo.caption}</span>
                </figcaption>
              </figure>
            </HorizontalScrollItem>
          ))}
        </HorizontalScrollTrack>
        <HorizontalScrollProgress />
      </HorizontalScroll>

      <section className="mx-auto flex min-h-[420px] max-w-6xl items-center px-5 sm:px-6 md:px-8">
        <p className={`${typography.lead} max-w-md`}>Prints from the series are available in editions of ten.</p>
      </section>
    </main>
  )
}
```

## API Reference

### HorizontalScroll

The section. Put an optional header, a `HorizontalScrollTrack` of `HorizontalScrollItem`s and a
`HorizontalScrollProgress` inside. While pinned, the section is exactly as tall as it needs to be
for the track to scroll from its first to its last item, and it recomputes that on resize. It pins
only when its contents fit the viewport's height (a short laptop window gets the swipeable row
instead of clipped cards). Tabbing to a card scrolls the page to where that card is in view.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Always use the native swipeable row (no pinning), e.g. inside a scrolling container. |

Also accepts every `div` prop.

### HorizontalScrollHeader

Header row above the track (eyebrow, title, a "Drag / Scroll" hint), aligned with the kit's page
container. Items share their last baseline, so a meta line sits on the title's baseline.

Also accepts every `div` prop.

### HorizontalScrollTrack

The row of `HorizontalScrollItem`s. Its first and last items line up with the page container
(`max-w-6xl`); override the inline padding with `className` to change that. When not pinned it's a
focusable, labelled region that scrolls with the arrow keys; in print the items wrap onto rows.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Scrollable content"` | Accessible name of the scrollable row (it's a labelled, focusable region in native mode). |

Also accepts every `div` prop.

### HorizontalScrollItem

One card in the row. Default width: most of a phone screen, about a third of a desktop.

Also accepts every `div` prop.

### HorizontalScrollProgress

A thin bar that fills as the row travels. Decorative: the row itself is what's navigable.

Also accepts every `div` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)



---

# Hover Video

> A muted clip that plays while its card is hovered or focused with the keyboard, over a poster or artwork. Loads nothing until then, pauses off screen and in background tabs, and stays still on touch screens, with reduced motion or when saving data.

Category: Utilities · Registry item: `@portfolio-kit/hover-video` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/hover-video) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/hover-video.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/hover-video
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/hover-video.tsx` and the kit items it uses: `use-composed-refs`, `use-in-view`, `use-page-visible`, `use-reduced-motion`, `use-save-data`.

## Usage

```tsx
import { HoverVideo } from "@/components/portfolio/hover-video"
```

## Examples

### Demo

A project card whose cover comes alive on hover: the still is the poster, the clip loads on first hover and plays muted while the card is hovered or focused.

```tsx
import { Play } from "lucide-react"

import { GenerativeArt } from "@/components/portfolio/generative-art"
import { HoverVideo } from "@/components/portfolio/hover-video"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"

export default function HoverVideoDemo() {
  return (
    <ProjectCard href="#tidewater" className="w-full max-w-sm">
      <ProjectCardMedia>
        {/* Your clip: a file in public/ ("/work/tidewater.mp4") or a CDN URL. The demo clip sits next to the docs preview. */}
        <HoverVideo src="media/showreel.mp4">
          {/* The still and its badges sit under the video, so they disappear once the clip plays. */}
          <GenerativeArt seed="tidewater-shore" variant="landscape" />
          <span aria-hidden className="absolute top-1/2 left-1/2 grid size-12 -translate-1/2 place-items-center rounded-full bg-black/45 text-white backdrop-blur-sm">
            <Play className="size-5 translate-x-px fill-current" />
          </span>
          <span className="absolute right-3 bottom-3 inline-flex h-6 items-center rounded-pill bg-black/60 px-2.5 font-mono text-[0.6875rem] tracking-[0.08em] text-white tabular-nums backdrop-blur-sm">
            <span className="sr-only">Video length</span> 0:12
          </span>
        </HoverVideo>
      </ProjectCardMedia>
      <ProjectCardContent>
        <ProjectCardMeta>
          <span>2025</span>
          <span>Motion identity</span>
        </ProjectCardMeta>
        <ProjectCardTitle>Tidewater</ProjectCardTitle>
        <ProjectCardDescription>An identity that moves like the sea it monitors: slow, layered, never still.</ProjectCardDescription>
      </ProjectCardContent>
    </ProjectCard>
  )
}
```

### In a list

A motion designer’s index: each row’s thumbnail plays its clip while the row is hovered or focused, and rewinds when you move on.

```tsx
import { ArrowUpRight } from "lucide-react"

import { GenerativeArt } from "@/components/portfolio/generative-art"
import { HoverVideo } from "@/components/portfolio/hover-video"

const films = [
  { slug: "salt-signal", title: "Salt & Signal idents", client: "Salt & Signal Radio", year: 2025, art: "landscape", hue: 212 },
  { slug: "northwind", title: "Northwind title sequence", client: "Northwind Films", year: 2025, art: "landscape", hue: 20 },
  { slug: "orbit-loops", title: "Product loops", client: "Orbit", year: 2024, art: "interface", hue: 170 },
] as const

export default function HoverVideoInAList() {
  return (
    <ul role="list" className="mx-auto flex w-full max-w-2xl flex-col divide-y border-y">
      {films.map((film) => (
        // HoverVideo listens to its closest <li>, so the whole row starts the clip.
        <li key={film.slug} className="group relative flex items-center gap-4 py-4 md:gap-6">
          <div className="relative aspect-video w-28 shrink-0 overflow-hidden rounded-lg border bg-muted md:w-40">
            {/* Your clip per row; the demo reuses one clip served next to the docs preview. */}
            <HoverVideo src="media/showreel.mp4" restart>
              <GenerativeArt seed={film.slug} variant={film.art} hue={film.hue} grain={false} />
            </HoverVideo>
          </div>
          <div className="flex min-w-0 flex-1 flex-col gap-1">
            <a
              href={`#${film.slug}`}
              className="truncate rounded-sm font-medium outline-none after:absolute after:inset-0 focus-visible:ring-[3px] focus-visible:ring-ring/50"
            >
              {film.title}
            </a>
            <span className="font-mono text-xs text-muted-foreground tabular-nums">
              {film.client} · {film.year}
            </span>
          </div>
          <ArrowUpRight
            aria-hidden
            className="size-4 shrink-0 text-muted-foreground transition-[translate,color] duration-300 ease-smooth group-hover:-translate-y-0.5 group-hover:translate-x-0.5 group-hover:text-highlight-ink"
          />
        </li>
      ))}
    </ul>
  )
}
```

## API Reference

### HoverVideo

Fills its parent (`size-full`), so put it in a sized media slot: `ProjectCardMedia`, `Media`, a panel.
The `<video>` uses `preload="none"` and only starts downloading on the first hover or keyboard focus.
It pauses while off screen or in a background tab. Under reduced motion, `prefers-reduced-data` or
Save-Data it never loads, and the poster or artwork stays.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` (required) | `string` | — | Video URL (MP4/WebM). Short, silent and small works best. |
| `poster` | `string` | — | Poster image shown before the first play (and while the clip is paused). |
| `children` | `React.ReactNode` | — | Artwork shown underneath until the clip plays, e.g. `<GenerativeArt />` or an `<img>`. |
| `trigger` | `string` | `"a, article, li"` | CSS selector for the ancestor whose hover/focus starts playback, e.g. a card. Defaults to the closest link, `<article>` (like `ProjectCard`) or `<li>`; otherwise the video itself. |
| `restart` | `boolean` | `false` | Rewind to the start when the pointer or focus leaves, instead of resuming where it stopped. |

Also accepts every `div` prop.

## Used in templates

- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)



---

# Image Gallery

> Images in a grid, masonry columns or a scrolling strip, with a lightbox you can use by keyboard, swipe or buttons.

Category: Work · Registry item: `@portfolio-kit/image-gallery` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/image-gallery) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/image-gallery.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/image-gallery
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/image-gallery.tsx` and the kit items it uses: `lightbox`, `media`, `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  GalleryItem,
  ImageGallery,
} from "@/components/portfolio/image-gallery"

<ImageGallery label="Studio notes" variant="masonry">
  <GalleryItem src="/studio-desk.jpg" alt="Desk with sketches" caption="Where it starts." />
  <GalleryItem src="/type-proofs.jpg" alt="Printed type proofs" caption="Proofing the type." />
  <GalleryItem src="/launch.jpg" alt="Team at the launch" />
</ImageGallery>
```

## Examples

### Demo

A square grid of process shots that opens into a keyboard- and swipe-friendly lightbox.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { GalleryItem, ImageGallery } from "@/components/portfolio/image-gallery"

const shots = [
  { seed: "workshop-guest", art: "portrait", alt: "Portrait of a turbine engineer interviewed for the Orbit sprint", caption: "User interviews, day two of the Orbit sprint." },
  { seed: "tide-study", art: "interface", alt: "First high-fidelity pass of the Tidewater dashboard", caption: "Tidewater dashboard, first high-fidelity pass." },
  { seed: "studio-view", art: "landscape", alt: "Morning light over the hills, seen from the studio window", caption: "The view from the studio, 7:40am — before anyone else arrives." },
  { seed: "poster-grid", art: "bauhaus", alt: "Poster series built on a four-column grid", caption: "Poster series for the Fieldnote launch, printed risograph." },
  { seed: "type-rings", art: "rings", alt: "Concentric type specimen", caption: "Type specimen, second proof." },
  { seed: "coast-walk", art: "landscape", alt: "Ridge line above the coast at dusk", caption: "Site visit to the Tidewater coast." },
] as const

export default function ImageGalleryDemo() {
  return (
    <ImageGallery label="Studio notes" className="mx-auto max-w-4xl">
      {shots.map((shot) => (
        <GalleryItem key={shot.seed} alt={shot.alt} caption={shot.caption}>
          <GenerativeArt seed={shot.seed} variant={shot.art} />
        </GalleryItem>
      ))}
    </ImageGallery>
  )
}
```

### Masonry

Mixed aspect ratios in balanced columns. Every image stays uncropped, which suits photography.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { GalleryItem, ImageGallery } from "@/components/portfolio/image-gallery"

const photos = [
  { seed: "lisbon-tram", art: "landscape", ratio: "portrait", alt: "Hills above Lisbon at dusk, from the tram", caption: "Line 28, Lisbon — Portra 400." },
  { seed: "harbour", art: "landscape", ratio: "photo", alt: "Hills above a quiet harbour at dawn", caption: "Harbour, early morning." },
  { seed: "tiles", art: "bauhaus", ratio: "square", alt: "Close-up of glazed wall tiles", caption: "Azulejo study." },
  { seed: "dunes", art: "landscape", ratio: "tall", alt: "Wind lines across coastal dunes", caption: "Dunes after the storm." },
  { seed: "window", art: "landscape", ratio: "photo", alt: "Late sun over the valley from the studio window", caption: "Studio window, 6pm." },
  { seed: "market", art: "portrait", ratio: "portrait", alt: "Portrait of a potter at her market stall", caption: "Kiln open day — the potter behind the seconds table." },
] as const

export default function ImageGalleryMasonry() {
  return (
    <ImageGallery variant="masonry" label="Film photography" className="mx-auto max-w-4xl">
      {photos.map((photo) => (
        <GalleryItem key={photo.seed} alt={photo.alt} caption={photo.caption} ratio={photo.ratio}>
          <GenerativeArt seed={photo.seed} variant={photo.art} />
        </GalleryItem>
      ))}
    </ImageGallery>
  )
}
```

### Strip

A horizontal, snap-scrolling row that fits a lot of work into one line of a case study.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { GalleryItem, ImageGallery } from "@/components/portfolio/image-gallery"

const frames = [
  { seed: "kiln-shop", art: "interface", ratio: "portrait", alt: "Kiln storefront home page on a phone", caption: "Home — the seasonal collection up front." },
  { seed: "kiln-product", art: "interface", ratio: "photo", alt: "Kiln product page with a large photo", caption: "Product page — one big photo, one clear button." },
  { seed: "kiln-pattern", art: "waves", ratio: "square", alt: "Packaging pattern for Kiln", caption: "Packaging pattern, printed on kraft." },
  { seed: "kiln-studio", art: "landscape", ratio: "portrait", alt: "The hills behind the studio on shooting day", caption: "Shooting day at the studio: the light we waited for." },
] as const

export default function ImageGalleryStrip() {
  return (
    <ImageGallery variant="strip" label="Kiln Ceramics" className="mx-auto max-w-5xl">
      {frames.map((frame) => (
        <GalleryItem key={frame.seed} alt={frame.alt} caption={frame.caption} ratio={frame.ratio}>
          <GenerativeArt seed={frame.seed} variant={frame.art} />
        </GalleryItem>
      ))}
    </ImageGallery>
  )
}
```

## API Reference

### ImageGallery

Direct children should be `<GalleryItem>`s (they're numbered for screen readers). Clicking one, or
Enter/Space on a focused one, opens the shared Lightbox viewer: the thumbnail zooms full screen, then
arrows, ← → keys or a swipe browse the set, and Esc returns focus to the thumbnail. Thumbnails keep
their `ratio` while images load, so the layout doesn't shift. The strip scrolls sideways by
touch, trackpad or Shift + wheel, and Tab brings each image into view.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"grid" \| "masonry" \| "strip"` | `"grid"` | `grid`: an even 2- or 3-column grid (square thumbnails by default). `masonry`: balanced columns that keep each image's own ratio. `strip`: one horizontal, snap-scrolling row of equal height. |
| `label` | `string` | `"Gallery"` | Accessible name for the gallery and its lightbox title. |
| `loop` | `boolean` | `true` | Wrap from the last image to the first (and back) in the lightbox. |
| `labels` | `Partial<LightboxLabels & { item: string }>` | — | Built-in text, for translations: `item`, each thumbnail's accessible name (`{alt}`, `{index}` and `{count}` are replaced), plus the lightbox's `previous`, `next`, `close`, `position`, `loading`, `unavailable` and `unavailableName`. |

Also accepts every `ul` prop.

### GalleryItem

One image: a thumbnail button that opens the lightbox at this image. `className` and extra props
go to the `<button>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alt` (required) | `string` | — | Describes what the image shows and why it's there, in a short sentence ("Printed type proofs pinned to the studio wall", not "image" or a file name). Required: it's also the name of the thumbnail button, and screen readers hear it followed by the image's position in the gallery. |
| `src` | `string` | — | Image URL, used for the thumbnail and the full-size view. Or pass artwork as `children`. |
| `caption` | `React.ReactNode` | — | Shown over the thumbnail on hover/focus and under the image in the lightbox. On touch screens (no hover) and in print it sits under the thumbnail instead. |
| `ratio` | `"square" \| "photo" \| "portrait" \| "tall" \| "video" \| "wide"` | — | Thumbnail ratio (also the artwork's ratio in the lightbox). Defaults to `square` in grids and `photo` elsewhere. |
| `children` | `React.ReactNode` | — | Artwork (e.g. <GenerativeArt />) used instead of `src`. Rendered in the thumbnail and the lightbox. |

Also accepts every `button` prop.

### type LightboxLabels

Built-in text of the viewer, for translations. `{index}`, `{count}` and `{alt}` are replaced.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `previous` (required) | `string` | — | Previous-item button. |
| `next` (required) | `string` | — | Next-item button. |
| `close` (required) | `string` | — | Close button. |
| `position` (required) | `string` | — | Position spoken with the counter and when browsing, e.g. "2 of 5". |
| `loading` (required) | `string` | — | Shown while a slow image loads. |
| `unavailable` (required) | `string` | — | Shown in place of an image that failed to load. |
| `unavailableName` (required) | `string` | — | Accessible name of that placeholder. |

## Used in templates

- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)



---

# Image Trail

> Images that spawn along the cursor's path and fade out behind it, over a hero or section. Touch screens and reduced motion get a still collage instead.

Category: Effects · Registry item: `@portfolio-kit/image-trail` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/image-trail) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/image-trail.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/image-trail
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/image-trail.tsx` and the kit items it uses: `use-composed-refs`, `use-fine-pointer`, `use-reduced-motion`.

## Usage

```tsx
import {
  ImageTrail,
  ImageTrailContent,
  ImageTrailTile,
  ImageTrailTiles,
} from "@/components/portfolio/image-trail"

<ImageTrail className="h-[560px]">
  <ImageTrailTiles>
    <ImageTrailTile>
      <img src="/work-1.jpg" alt="" />
    </ImageTrailTile>
    <ImageTrailTile>
      <img src="/work-2.jpg" alt="" />
    </ImageTrailTile>
  </ImageTrailTiles>
  <ImageTrailContent>
    <h1>Mara Lindqvist</h1>
    <a href="#work">See the work</a>
  </ImageTrailContent>
</ImageTrail>
```

## Examples

### Demo

A photographer's hero: on first view a few images settle around the name, then move the cursor and work spills out behind it. On touch screens they sit still as a collage.

```tsx
import { MousePointer2 } from "lucide-react"

import { ArrowLink } from "@/components/portfolio/arrow-link"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ImageTrail,
  ImageTrailContent,
  ImageTrailTile,
  ImageTrailTiles,
} from "@/components/portfolio/image-trail"
import { typography } from "@/lib/typography"

const work = [
  { seed: "harbour-dawn", variant: "landscape" },
  { seed: "studio-portrait", variant: "portrait" },
  { seed: "salt-flats", variant: "landscape" },
  { seed: "night-market", variant: "portrait" },
  { seed: "north-coast", variant: "landscape" },
  { seed: "paper-city", variant: "portrait" },
  { seed: "blue-hour", variant: "landscape" },
  { seed: "ferry-crew", variant: "portrait" },
] as const

export default function ImageTrailDemo() {
  return (
    <ImageTrail className="h-[560px]">
      <ImageTrailTiles>
        {work.map((image) => (
          <ImageTrailTile key={image.seed}>
            <GenerativeArt seed={image.seed} variant={image.variant} />
          </ImageTrailTile>
        ))}
      </ImageTrailTiles>
      <ImageTrailContent className="gap-6 px-6">
        <p className={typography.eyebrow}>Photography &amp; art direction</p>
        <h1 className={typography.display}>Mara Lindqvist</h1>
        <p className={`${typography.lead} max-w-lg`}>
          Editorial and campaign work for people who make quiet, careful things.
        </p>
        <ArrowLink href="#work" tone="highlight" className="text-base md:text-lg">
          See the work
        </ArrowLink>
      </ImageTrailContent>
      {/* Only where the trail can run: hidden on touch screens and with reduced motion. */}
      <p
        aria-hidden
        className={`${typography.eyebrow} absolute inset-x-0 bottom-6 flex items-center justify-center gap-2 [@media(hover:none)]:hidden [@media(pointer:coarse)]:hidden motion-reduce:hidden`}
      >
        <MousePointer2 className="size-3.5" />
        Move your cursor
      </p>
    </ImageTrail>
  )
}
```

### In a Card

A denser, straighter trail inside a contact card. Lower `threshold` packs images closer; `rotation={0}` keeps them square to the grid.

```tsx
import { buttonVariants } from "@/components/ui/button"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ImageTrail,
  ImageTrailContent,
  ImageTrailTile,
  ImageTrailTiles,
} from "@/components/portfolio/image-trail"
import { typography } from "@/lib/typography"

const seeds = ["ink", "moss", "clay", "tide", "ember", "slate", "pollen", "frost", "dune", "fern"]

export default function ImageTrailInACard() {
  return (
    <ImageTrail
      threshold={48}
      rotation={0}
      duration={900}
      className="mx-auto h-96 max-w-4xl rounded-2xl border bg-card text-card-foreground shadow-card"
    >
      <ImageTrailTiles>
        {seeds.map((seed) => (
          <ImageTrailTile key={seed} className="aspect-square w-20 rounded-lg md:w-24">
            <GenerativeArt seed={seed} variant="bauhaus" grain={false} />
          </ImageTrailTile>
        ))}
      </ImageTrailTiles>
      <ImageTrailContent className="gap-5 px-6">
        <h2 className={typography.title}>Have a project in mind?</h2>
        <a href="mailto:hello@example.com" className={buttonVariants({ size: "lg" })}>
          hello@example.com
        </a>
      </ImageTrailContent>
    </ImageTrail>
  )
}
```

## API Reference

### ImageTrail

The hover area. Put an `ImageTrailTiles` (the image pool) and your content inside; content sits
above the images and stays interactive. Give it a height (`min-h-[70vh]`, `aspect-video`…).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `threshold` | `number` | `80` | Distance in px the pointer must travel before the next image appears. Lower is denser. |
| `duration` | `number` | `1100` | How long each image lives, in ms (pop in, hold, fall away). |
| `rotation` | `number` | `8` | Maximum random tilt of each image, in degrees. `0` keeps them straight. |
| `autoplay` | `boolean` | `true` | On first view, trace a short trail on its own and leave those images resting in an arc around the content, so the area never looks empty before someone moves the cursor. The first real pointer move clears them and hands over to the live trail. Runs once. |
| `disabled` | `boolean` | `false` | Turn the trail off (it's already off on touch screens and with reduced motion). Mouse users then see only the content; touch and reduced motion keep the still collage. |

Also accepts every `div` prop.

### ImageTrailTiles

The image pool: put 6–12 `ImageTrailTile`s inside, as direct children. They're decorative
(`aria-hidden`) and never catch the pointer. The pool is recycled, so at most this many images
are on screen at once. The first six also form the still collage.

Also accepts every `div` prop.

### ImageTrailTile

One image in the pool. Put an `<img>` or `<GenerativeArt />` inside; size it with `className`
(default: a 4:5 card, `w-28` on phones, `w-44` from `md`).

Also accepts every `div` prop.

### ImageTrailContent

Your content (headline, CTA), centered above the images by default. Stays clickable.

Also accepts every `div` prop.



---

# Kbd

> Keycaps and shortcut hints ("⌘K to search", "Press Esc") that show ⌘ or Ctrl for the visitor's platform and read as words to screen readers.

Category: Utilities · Registry item: `@portfolio-kit/kbd` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/kbd) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/kbd.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/kbd
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/kbd.tsx`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import { Kbd, KbdShortcut } from "@/components/portfolio/kbd"

<p>
  Press <KbdShortcut keys={["mod", "k"]} /> to search or <Kbd>Esc</Kbd> to close.
</p>
```

## Examples

### Demo

A keyboard-shortcuts legend for a portfolio: ⌘ or Ctrl follows the visitor's device, and every symbol is read as a word.

```tsx
import { KbdShortcut } from "@/components/portfolio/kbd"
import { typography } from "@/lib/typography"

const shortcuts = [
  { action: "Search the site", keys: ["mod", "k"] },
  { action: "Next project", keys: ["j"] },
  { action: "Previous project", keys: ["k"] },
  { action: "Turn effects off", keys: ["esc"] }
]

export default function KbdDemo() {
  return (
    <div className="w-full max-w-sm rounded-2xl border bg-card p-5 shadow-card md:p-6">
      <p className={typography.eyebrow}>Shortcuts</p>
      <dl className="mt-3">
        {shortcuts.map((s) => (
          <div key={s.action} className="flex items-center justify-between gap-4 border-b py-3 last:border-b-0 last:pb-0">
            <dt className="text-sm text-foreground">{s.action}</dt>
            <dd>
              <KbdShortcut keys={s.keys} size="md" />
            </dd>
          </div>
        ))}
      </dl>
    </div>
  )
}
```

### Inline hints

"Press this" hints inside running text, the way portfolios announce hidden shortcuts: `md` in body copy, the default `sm` in small meta text.

```tsx
import { Kbd, KbdShortcut } from "@/components/portfolio/kbd"
import { typography } from "@/lib/typography"

export default function KbdInline() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <p className={typography.body}>
        Press <KbdShortcut keys={["mod", "k"]} size="md" /> to jump to any project, or <Kbd size="md">Esc</Kbd> to turn
        the effects off.
      </p>
      <p className={typography.body}>
        On a case study, press <Kbd size="md">I</Kbd> for credits and <KbdShortcut keys={["shift", "?"]} size="md" /> for
        every shortcut.
      </p>
      <p className={typography.meta}>
        Use <KbdShortcut keys={["left"]} /> <KbdShortcut keys={["right"]} /> to browse the gallery
      </p>
    </div>
  )
}
```

### Per platform

Force a platform to document both: ⌘ symbols on macOS, words joined with "+" on Windows and Linux.

```tsx
import { KbdShortcut } from "@/components/portfolio/kbd"
import { typography } from "@/lib/typography"

const combos = [
  { action: "Search", keys: ["mod", "k"] },
  { action: "Copy email", keys: ["mod", "shift", "c"] },
  { action: "Delete line", keys: ["mod", "backspace"] }
]

export default function KbdPlatforms() {
  return (
    <div className="grid w-full max-w-md gap-6 sm:grid-cols-2">
      {(["mac", "other"] as const).map((platform) => (
        <div key={platform} className="flex flex-col gap-3">
          <p className={typography.eyebrow}>{platform === "mac" ? "macOS" : "Windows & Linux"}</p>
          <ul role="list" className="flex flex-col gap-2.5">
            {combos.map((c) => (
              <li key={c.action} className="flex items-center justify-between gap-3 text-sm text-foreground">
                {c.action}
                <KbdShortcut keys={c.keys} platform={platform} separator={platform === "other" ? "+" : undefined} />
              </li>
            ))}
          </ul>
        </div>
      ))}
    </div>
  )
}
```

### Sizes

`sm` for buttons and menus, `md` for running text, `lg` for a standalone prompt on a 404 or an intro screen.

```tsx
import { Kbd, KbdShortcut } from "@/components/portfolio/kbd"

export default function KbdSizes() {
  return (
    <div className="flex flex-col items-center gap-5">
      {(["sm", "md", "lg"] as const).map((size) => (
        <div key={size} className="flex items-center gap-3">
          <KbdShortcut keys={["mod", "k"]} size={size} />
          <Kbd size={size}>Esc</Kbd>
          <KbdShortcut keys={["shift", "?"]} size={size} />
        </div>
      ))}
    </div>
  )
}
```

## API Reference

### Kbd

One keycap: a `<kbd>` with whatever you put inside (a letter, a word such as `Esc`, or an icon).
Write words, not symbols, or add a screen-reader label yourself; `KbdShortcut` does that for you.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | `"sm"` | `sm` for hints inside buttons, menus and dense text, `md` for running text, `lg` for a standalone "press this" prompt. |

Also accepts every `kbd` prop.

### KbdShortcut

A key combination: an outer `<kbd>` holding one `Kbd` per key, as HTML specifies for shortcuts.
Symbols are hidden from screen readers and replaced with their names ("Command K").

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keys` (required) | `string[]` | — | Keys in order, e.g. `["mod", "k"]` or `["shift", "?"]`. `mod` is ⌘ on Apple devices and Ctrl elsewhere. Also understood: `cmd`, `ctrl`, `alt`/`option`, `shift`, `enter`, `esc`, `tab`, `space`, `backspace`, `delete`, `up`/`down`/`left`/`right` (or `↑ ↓ ← →`), `capslock`, `pageup`, `pagedown`. Single characters are capitalised; anything else is shown as written. |
| `size` | `"sm" \| "md" \| "lg"` | `"sm"` | Keycap size (see `Kbd`). |
| `platform` | `"auto" \| "mac" \| "other"` | `"auto"` | `auto` follows the visitor's device after hydration. Force `mac` or `other` to document one platform. |
| `separator` | `React.ReactNode` | — | Shown between keys, e.g. `"+"` for the Windows convention. Screen readers announce it too. |
| `labels` | `KbdLabels` | — | Spoken names of the named keys, to translate them: `{ shift: "Maj" }`, or `{ alt: { mac: "Option", other: "Alt" } }` per platform. Keys you leave out keep their English names. |

Also accepts every `kbd` prop.

### type KbdLabels

Spoken key names by key, e.g. `{ shift: "Maj", esc: "Échap" }`. A string is used on every platform;
`{ mac, other }` sets each (`mod` is Command on Apple devices and Control elsewhere).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `right` | `string \| { mac?: string; other?: string; }` | — |  |
| `alt` | `string \| { mac?: string; other?: string; }` | — |  |
| `enter` | `string \| { mac?: string; other?: string; }` | — |  |
| `tab` | `string \| { mac?: string; other?: string; }` | — |  |
| `shift` | `string \| { mac?: string; other?: string; }` | — |  |
| `left` | `string \| { mac?: string; other?: string; }` | — |  |
| `mod` | `string \| { mac?: string; other?: string; }` | — |  |
| `ctrl` | `string \| { mac?: string; other?: string; }` | — |  |
| `backspace` | `string \| { mac?: string; other?: string; }` | — |  |
| `delete` | `string \| { mac?: string; other?: string; }` | — |  |
| `cmd` | `string \| { mac?: string; other?: string; }` | — |  |
| `esc` | `string \| { mac?: string; other?: string; }` | — |  |
| `space` | `string \| { mac?: string; other?: string; }` | — |  |
| `up` | `string \| { mac?: string; other?: string; }` | — |  |
| `down` | `string \| { mac?: string; other?: string; }` | — |  |
| `capslock` | `string \| { mac?: string; other?: string; }` | — |  |
| `pageup` | `string \| { mac?: string; other?: string; }` | — |  |
| `pagedown` | `string \| { mac?: string; other?: string; }` | — |  |

## Used in templates

- [Not Found](https://www.parthjadhav.com/products/portfolio-kit/templates/not-found.md)
- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)



---

# Lab Grid

> Dense grid of side projects, experiments and toys, each with a status (live, WIP, archived), a small preview and a one-line meta row. Also renders as compact text rows.

Category: Work · Registry item: `@portfolio-kit/lab-grid` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/lab-grid) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/lab-grid.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/lab-grid
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/lab-grid.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  LabGrid,
  LabItem,
  LabItemContent,
  LabItemMeta,
  LabItemPreview,
  LabItemStatus,
  LabItemTitle,
} from "@/components/portfolio/lab-grid"

<LabGrid columns={3}>
  <LabItem href="/lab/ripple" status="live">
    <LabItemPreview>
      <img src="/lab/ripple.jpg" alt="" />
    </LabItemPreview>
    <LabItemContent>
      <LabItemTitle>Ripple shader</LabItemTitle>
      <LabItemStatus />
      <LabItemMeta>
        <time dateTime="2025">2025</time>
        <span>WebGL</span>
      </LabItemMeta>
    </LabItemContent>
  </LabItem>
</LabGrid>
```

## Examples

### Demo

A playground page: eight experiments as small tiles with a status, year and tool. Hover the first tile to play its clip.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { HoverVideo } from "@/components/portfolio/hover-video"
import {
  LabGrid,
  LabItem,
  LabItemContent,
  LabItemMeta,
  LabItemPreview,
  LabItemStatus,
  LabItemTitle,
} from "@/components/portfolio/lab-grid"

const experiments = [
  { slug: "ripple", title: "Ripple shader", year: 2025, tool: "WebGL", status: "live", art: "waves", hue: 205, clip: true },
  { slug: "type-tester", title: "Variable type tester", year: 2025, tool: "Figma plugin", status: "wip", art: "interface", hue: 30 },
  { slug: "orbit", title: "Orbit clock", year: 2025, tool: "Canvas", status: "live", art: "rings", hue: 265 },
  { slug: "tiny-synth", title: "Tiny synth", year: 2024, tool: "Web Audio", status: "live", art: "orb", hue: 330 },
  { slug: "grid-gen", title: "Grid generator", year: 2024, tool: "CLI", status: "wip", art: "bauhaus", hue: 140 },
  { slug: "moodboard", title: "Moodboard bot", year: 2024, tool: "Raycast", status: "archived", art: "interface", hue: 175 },
  { slug: "dither", title: "Dither studio", year: 2023, tool: "WebGPU", status: "live", art: "mesh", hue: 10 },
  { slug: "trail", title: "Trail map", year: 2023, tool: "Mapbox", status: "archived", art: "landscape", hue: 95 },
] as const

export default function LabGridDemo() {
  return (
    <LabGrid columns={4} aria-label="Experiments" className="mx-auto max-w-6xl">
      {experiments.map((item) => (
        <LabItem key={item.slug} href={`#${item.slug}`} status={item.status}>
          <LabItemPreview>
            {"clip" in item ? (
              // Your clip: a file in public/ ("/lab/ripple.mp4"). It loads on first hover and plays one at a time.
              <HoverVideo src="media/showreel.mp4">
                <GenerativeArt seed={item.slug} variant={item.art} hue={item.hue} />
              </HoverVideo>
            ) : (
              <GenerativeArt seed={item.slug} variant={item.art} hue={item.hue} />
            )}
          </LabItemPreview>
          <LabItemContent>
            <LabItemTitle>{item.title}</LabItemTitle>
            <LabItemStatus />
            <LabItemMeta>
              <time dateTime={String(item.year)}>{item.year}</time>
              <span>{item.tool}</span>
            </LabItemMeta>
          </LabItemContent>
        </LabItem>
      ))}
    </LabGrid>
  )
}
```

### With filter

Filter the lab by kind with filter chips; `LabGridEmpty` covers a kind with nothing in it yet.

```tsx
import * as React from "react"

import { FilterChip, FilterChips } from "@/components/portfolio/filter-chips"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  LabGrid,
  LabGridEmpty,
  LabItem,
  LabItemContent,
  LabItemMeta,
  LabItemPreview,
  LabItemStatus,
  LabItemTitle,
} from "@/components/portfolio/lab-grid"

const kinds = ["All", "Shaders", "Tools", "Sound", "Games"] as const

const experiments = [
  { slug: "ripple", title: "Ripple shader", year: 2025, kind: "Shaders", tool: "WebGL", status: "live", art: "waves", hue: 205 },
  { slug: "dither", title: "Dither studio", year: 2025, kind: "Shaders", tool: "WebGPU", status: "wip", art: "mesh", hue: 10 },
  { slug: "grid-gen", title: "Grid generator", year: 2024, kind: "Tools", tool: "CLI", status: "live", art: "bauhaus", hue: 140 },
  { slug: "palette", title: "Palette from photo", year: 2024, kind: "Tools", tool: "Web app", status: "live", art: "interface", hue: 48 },
  { slug: "tiny-synth", title: "Tiny synth", year: 2024, kind: "Sound", tool: "Web Audio", status: "archived", art: "orb", hue: 330 },
  { slug: "orbit", title: "Orbit clock", year: 2023, kind: "Tools", tool: "Canvas", status: "archived", art: "rings", hue: 265 },
] as const

export default function LabGridWithFilter() {
  const [kind, setKind] = React.useState<string>("All")
  const visible = kind === "All" ? experiments : experiments.filter((item) => item.kind === kind)

  return (
    <div className="mx-auto flex max-w-5xl flex-col gap-8">
      <FilterChips type="single" required value={kind} onValueChange={setKind} size="sm" aria-label="Filter experiments by kind">
        {kinds.map((k) => (
          <FilterChip
            key={k}
            value={k}
            label={k}
            count={k === "All" ? experiments.length : experiments.filter((item) => item.kind === k).length}
          />
        ))}
      </FilterChips>
      {/* Announce the result count when the filter changes. */}
      <p aria-live="polite" className="sr-only">
        {visible.length === 1 ? "1 experiment" : `${visible.length} experiments`}
      </p>
      {visible.length === 0 ? (
        <LabGridEmpty>No {kind.toLowerCase()} yet. Something is brewing.</LabGridEmpty>
      ) : (
        <LabGrid aria-label="Experiments">
          {visible.map((item) => (
            <LabItem key={item.slug} href={`#${item.slug}`} status={item.status}>
              <LabItemPreview>
                <GenerativeArt seed={item.slug} variant={item.art} hue={item.hue} />
              </LabItemPreview>
              <LabItemContent>
                <LabItemTitle>{item.title}</LabItemTitle>
                <LabItemStatus />
                <LabItemMeta>
                  <time dateTime={String(item.year)}>{item.year}</time>
                  <span>{item.tool}</span>
                </LabItemMeta>
              </LabItemContent>
            </LabItem>
          ))}
        </LabGrid>
      )}
    </div>
  )
}
```

### Compact

Text-only rows for minimal sites: title, year and tool, and a status, two columns on wide screens. Previews are dropped; a project hosted elsewhere opens in a new tab and shows ↗.

```tsx
import {
  LabGrid,
  LabItem,
  LabItemContent,
  LabItemMeta,
  LabItemStatus,
  LabItemTitle,
} from "@/components/portfolio/lab-grid"

const experiments = [
  { slug: "ripple", title: "Ripple shader", year: 2025, tool: "WebGL", status: "live" },
  { slug: "type-tester", title: "Variable type tester", year: 2025, tool: "Figma", status: "wip" },
  { slug: "orbit", title: "Orbit clock", year: 2025, tool: "Canvas", status: "live" },
  { slug: "tiny-synth", title: "Tiny synth", year: 2024, tool: "Web Audio", status: "live", href: "https://tiny-synth.example.com" },
  { slug: "grid-gen", title: "Grid generator", year: 2024, tool: "CLI", status: "wip" },
  { slug: "moodboard", title: "Moodboard bot", year: 2024, tool: "Raycast", status: "archived" },
  { slug: "dither", title: "Dither studio", year: 2023, tool: "WebGPU", status: "live" },
  { slug: "trail", title: "Trail map", year: 2023, tool: "Mapbox", status: "archived" },
] as const

export default function LabGridCompact() {
  return (
    <LabGrid variant="compact" columns={2} aria-label="Experiments" className="mx-auto max-w-4xl">
      {experiments.map((item) => (
        <LabItem key={item.slug} href={"href" in item ? item.href : `#${item.slug}`} status={item.status}>
          <LabItemContent>
            <LabItemTitle>{item.title}</LabItemTitle>
            <LabItemStatus />
            <LabItemMeta>
              <time dateTime={String(item.year)}>{item.year}</time>
              <span>{item.tool}</span>
            </LabItemMeta>
          </LabItemContent>
        </LabItem>
      ))}
    </LabGrid>
  )
}
```

## API Reference

### LabGrid

The grid, a `<ul>` (with `role="list"`, so Safari keeps the list semantics of an unstyled list). Each
child must be a `LabItem` (an `<li>`). Label it with `aria-label` or `aria-labelledby` when it has no
heading nearby.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"tile" \| "compact"` | `"tile"` | `tile`: small bordered cards with a preview on top. `compact`: text-only rows (title, meta, status) for minimal sites; previews are hidden. |
| `columns` | `2 \| 3 \| 4` | `3` | Columns on wide screens. Tiles are two columns up to `lg`, then 3, and 4 from `xl` (with `4`); in the narrow phone tiles the status sits under the meta. For one tile per row on phones, add `className="max-sm:grid-cols-1"`. Compact rows are one column up to `lg`, then two (three from `2xl` with `4`). |

Also accepts every `ul` prop.

### LabItem

One experiment, an `<li>`. Holds the link and status for the parts inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | Makes the whole item one link (on the title, stretched over the item). Absolute URLs open in a new tab and show ↗ after the title. |
| `status` | `"live" \| "wip" \| "archived"` | — | Where the project stands, shown by `LabItemStatus` as a labelled dot: `live` (success), `wip` (highlight) or `archived` (muted). Also set as `data-status` for styling or filtering. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added to the title link when `href` opens in a new tab. Translate it for your site's language. |

Also accepts every `li` prop.

### LabItemPreview

Preview slot (4:3) for an `<img>`, `<GenerativeArt />` or `<HoverVideo>` (a clip that plays while
the item is hovered or focused). Decorative: hidden from assistive tech, since the title names the
item. Not rendered in the `compact` variant.

Also accepts every `div` prop.

### LabItemContent

Text area. Put `LabItemTitle`, `LabItemStatus` and `LabItemMeta` inside, in that order: tiles show
the status beside the title with the meta underneath (on phones, the status goes under the meta);
compact rows show title, meta, status in a line.

Also accepts every `div` prop.

### LabItemTitle

The item's name. With `href` on the item it holds the link, stretched over the whole item; links that
open in a new tab show ↗ and the item's `newTabLabel`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level. Match your page outline (`h2` when the grid sits directly under the page title). |

Also accepts every `h3` prop.

### LabItemStatus

Status badge: a dot plus a text label (`Live`, `WIP`, `Archived`), so it never relies on color
alone. Reads the item's `status`; pass children to change the label (e.g. "In progress").
Renders nothing when there's no status.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"live" \| "wip" \| "archived"` | — | Overrides the item's `status`. |

Also accepts every `span` prop.

### LabItemMeta

Small mono line: year, tool or stack, kind. Pass `<span>`s or a `<time>`; they're separated by
slashes. Spans the full width under the title in tiles; sits between title and status in compact rows.

Also accepts every `div` prop.

### LabGridEmpty

Placeholder for a grid with nothing to show (e.g. a filter with no matches). Render it *instead of*
the grid. It's a polite live region, so screen readers hear the message when a filter empties the list.

Also accepts every `div` prop.



---

# Language Switch

> Links to the translated versions of a page, as “EN / DE / FR” text, a segmented pill or a globe menu. Sets `hrefLang`, `lang` and `aria-current` for you.

Category: Navigation · Registry item: `@portfolio-kit/language-switch` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/language-switch) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/language-switch.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/language-switch
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/language-switch.tsx` and the kit items it uses: `use-composed-refs`.

npm dependencies: `class-variance-authority`, `lucide-react`, `radix-ui`.

## Usage

```tsx
import {
  LanguageSwitch,
  LanguageSwitchItem,
} from "@/components/portfolio/language-switch"

<LanguageSwitch>
  <LanguageSwitchItem href="/en/" locale="en" label="English" active />
  <LanguageSwitchItem href="/de/" locale="de" label="Deutsch" />
  <LanguageSwitchItem href="/fr/" locale="fr" label="Français" />
</LanguageSwitch>
```

## Examples

### Demo

“EN / DE / FR” in the corner of a header: each link points at the same page in another language.

```tsx
import { LanguageSwitch, LanguageSwitchItem } from "@/components/portfolio/language-switch"
import { typography } from "@/lib/typography"

export default function LanguageSwitchDemo() {
  return (
    <div className="mx-auto flex max-w-3xl flex-col gap-10">
      <header className="flex items-center justify-between gap-6 border-b pb-5">
        <a
          href="#top"
          className="rounded-md font-heading text-lg outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
        >
          Mara Lindqvist
        </a>
        <LanguageSwitch>
          <LanguageSwitchItem href="/en/" locale="en" label="English" active />
          <LanguageSwitchItem href="/de/" locale="de" label="Deutsch" />
          <LanguageSwitchItem href="/fr/" locale="fr" label="Français" />
        </LanguageSwitch>
      </header>
      <div className="flex flex-col gap-3">
        <p className={typography.eyebrow}>Product designer · Stockholm</p>
        <p className="font-heading text-2xl leading-tight text-balance md:text-3xl">
          Also available in Deutsch and Français — same page, same work.
        </p>
      </div>
    </div>
  )
}
```

### Segmented

The current language filled in a pill, for footers and settings rows.

```tsx
import { LanguageSwitch, LanguageSwitchItem } from "@/components/portfolio/language-switch"

export default function LanguageSwitchSegmented() {
  return (
    <div className="flex w-full max-w-sm items-center justify-between gap-4 rounded-2xl border bg-card p-4 pl-5 text-card-foreground shadow-card">
      <p className="text-sm text-muted-foreground">Read this site in</p>
      <LanguageSwitch variant="segmented">
        <LanguageSwitchItem href="/en/" locale="en" label="English" />
        <LanguageSwitchItem href="/nl/" locale="nl" label="Nederlands" active />
        <LanguageSwitchItem href="/es/" locale="es" label="Español" />
      </LanguageSwitch>
    </div>
  )
}
```

### Menu

A globe button that lists native names, for four or more languages. `children` replaces a code, e.g. for scripts.

```tsx
import { LanguageSwitch, LanguageSwitchItem } from "@/components/portfolio/language-switch"

export default function LanguageSwitchMenu() {
  return (
    <div className="flex h-72 w-full max-w-md items-start justify-end">
      <LanguageSwitch variant="menu">
        <LanguageSwitchItem href="/en/" locale="en" label="English" active />
        <LanguageSwitchItem href="/de/" locale="de" label="Deutsch" />
        <LanguageSwitchItem href="/pt-br/" locale="pt-BR" label="Português (Brasil)">
          PT
        </LanguageSwitchItem>
        <LanguageSwitchItem href="/ja/" locale="ja" label="日本語" />
        <LanguageSwitchItem href="/uk/" locale="uk" label="Українська" />
      </LanguageSwitch>
    </div>
  )
}
```

## API Reference

### LanguageSwitch

A `<nav>` labelled "Language" around a list of `LanguageSwitchItem`s. Every link carries `hrefLang` and `lang`,
and the active one `aria-current="page"`.

The `menu` variant is a disclosure: a button with `aria-expanded` that shows the same list of links. Opening
it focuses the current language; ↑/↓, Home and End move between links, Esc closes and returns to the button,
and Tab moves on (closing it). The list isn't portalled, so the links stay inside the `<nav>` landmark.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"text" \| "segmented" \| "menu"` | `"text"` | `text`: "EN / DE / FR" in mono caps, for headers and footers. `segmented`: the same codes in a pill with the current one filled. `menu`: a globe button that opens a list of native names — for 4+ languages. |
| `children` | `React.ReactNode` | — | `LanguageSwitchItem`s, as direct children (the `menu` variant reads the active one for its button). |
| `side` | `"top" \| "bottom"` | `"bottom"` | Popover side for the `menu` variant. |
| `align` | `"start" \| "center" \| "end"` | `"end"` | Popover alignment for the `menu` variant. |
| `label` | `string` | `"Language"` | Accessible name of the `<nav>`; also the `menu` button's text when no item is `active`. |
| `triggerLabel` | `string` | `"Change language"` | Screen-reader hint after the current language on the `menu` button. |

Also accepts every `nav` prop.

### LanguageSwitchItem

One language. `children` replaces the visible code (e.g. "中文" instead of "ZH").

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` (required) | `string` | — | URL of this page in that language, e.g. `"/de/about"`. |
| `locale` (required) | `string` | — | BCP 47 language tag, e.g. `"de"` or `"pt-BR"`. Sets `hrefLang`/`lang`; shown uppercased when there are no `children`. |
| `label` | `string` | — | The language's native name, e.g. "Deutsch". Visible in the `menu`; for screen readers after the code elsewhere. |
| `active` | `boolean` | `false` | The language of the current page: marked `aria-current="page"` and highlighted. |

Also accepts every `a` prop.



---

# Lightbox

> Click-to-expand viewer for images, artwork and video: the thumbnail zooms into a full-screen view you browse with arrows, keys or swipes.

Category: Work · Registry item: `@portfolio-kit/lightbox` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/lightbox) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/lightbox.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/lightbox
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/lightbox.tsx` and the kit items it uses: `typography`, `use-reduced-motion`.

npm dependencies: `lucide-react`, `radix-ui`.

## Usage

```tsx
import {
  Lightbox,
  LightboxTrigger,
} from "@/components/portfolio/lightbox"

<Lightbox label="Tidewater" className="grid grid-cols-2 gap-4">
  <LightboxTrigger alt="Dashboard overview" caption="Overview">
    <img src="/work/tidewater-1.jpg" alt="" />
  </LightboxTrigger>
  <LightboxTrigger alt="Turbine detail view" caption="Detail">
    <img src="/work/tidewater-2.jpg" alt="" />
  </LightboxTrigger>
</Lightbox>
```

## Examples

### Demo

A case-study image grid: click any shot to zoom it full screen, then browse with the arrows, ← → keys or a swipe.

```tsx
import { Maximize2 } from "lucide-react"

import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Lightbox, LightboxTrigger } from "@/components/portfolio/lightbox"

const shots = [
  {
    seed: "tidewater-coast",
    art: "landscape",
    alt: "The Tidewater array offshore at dusk",
    caption: "Site visit: 64 turbines, twelve miles out, and one control room watching all of them.",
    className: "col-span-2 aspect-[16/9]",
  },
  {
    seed: "tidewater-hero",
    art: "interface",
    alt: "Tidewater dashboard on a wall display",
    caption: "The control-room view: every turbine on one screen, anomalies surfacing first.",
    className: "aspect-square",
  },
  {
    seed: "tidewater-ops",
    art: "portrait",
    alt: "A night-shift operator in the Tidewater control room",
    caption: "Alert states were tested with night-shift operators before a single pixel was polished.",
    className: "aspect-square",
  },
] as const

export default function LightboxDemo() {
  return (
    <Lightbox label="Tidewater" className="mx-auto grid w-full max-w-2xl grid-cols-2 gap-3 md:gap-4">
      {shots.map((shot) => (
        <LightboxTrigger
          key={shot.seed}
          alt={shot.alt}
          caption={shot.caption}
          className={shot.className}
          // The viewer shows the artwork alone, without the expand hint.
          content={<GenerativeArt seed={shot.seed} variant={shot.art} />}
        >
          <GenerativeArt seed={shot.seed} variant={shot.art} />
          <span
            aria-hidden
            className="absolute right-3 bottom-3 flex size-9 items-center justify-center rounded-pill bg-black/45 text-white ring-1 ring-white/20 backdrop-blur-md"
          >
            <Maximize2 className="size-4" />
          </span>
        </LightboxTrigger>
      ))}
    </Lightbox>
  )
}
```

### In an article

Triggers can sit anywhere inside `<Lightbox>`, at any depth: figures scattered through a case study still open as one set, in reading order.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Lightbox, LightboxTrigger } from "@/components/portfolio/lightbox"

export default function LightboxInAnArticle() {
  return (
    <Lightbox label="Kiln Ceramics" className="mx-auto w-full max-w-xl">
      <article className="flex flex-col gap-6 text-sm leading-relaxed text-pretty text-muted-foreground md:text-base">
        <p>
          Kiln sells one-off pieces, so every product page is also a portrait. We started by photographing the whole
          collection against the same wall, at the same hour.
        </p>
        <figure className="flex flex-col gap-3">
          <LightboxTrigger
            alt="Glazed bowls drying on a wooden shelf"
            caption="Batch 14, drying. The shelf became the site's grid."
            className="aspect-[3/2]"
          >
            <GenerativeArt seed="kiln-shelf" variant="landscape" hue={30} />
          </LightboxTrigger>
          <figcaption className="font-mono text-xs text-muted-foreground">Fig. 1 — The studio shelf</figcaption>
        </figure>
        <p>
          The pattern library came from the glazes themselves: each colourway maps to a tone the storefront can use for
          accents, badges and empty states.
        </p>
        <div className="grid grid-cols-2 gap-3">
          <LightboxTrigger alt="Glaze swatches, warm set" caption="Warm glazes: ember, clay, rust." className="aspect-[4/5]">
            <GenerativeArt seed="kiln-warm" variant="mesh" />
          </LightboxTrigger>
          <LightboxTrigger alt="Glaze swatches, cool set" caption="Cool glazes: slate, sea, moss." className="aspect-[4/5]">
            <GenerativeArt seed="kiln-cool" variant="mesh" hue={200} />
          </LightboxTrigger>
        </div>
      </article>
    </Lightbox>
  )
}
```

### Single image

One image on its own: no counter, no arrows — just zoom in, and tap, swipe down or press Esc to put it back.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Lightbox, LightboxTrigger } from "@/components/portfolio/lightbox"

export default function LightboxSingle() {
  return (
    <Lightbox label="Poster" className="w-full max-w-xs">
      <LightboxTrigger
        alt="Poster for the Fieldnote launch, risograph on cream paper"
        caption="Fieldnote launch poster — two-colour risograph, A2."
        className="aspect-[3/4] rounded-2xl border"
      >
        <GenerativeArt seed="fieldnote-poster" variant="bauhaus" />
      </LightboxTrigger>
    </Lightbox>
  )
}
```

### With photo details

Captions take block content: each photograph opens with a line of text and its shooting data from `<PhotoMeta>`.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Lightbox, LightboxTrigger } from "@/components/portfolio/lightbox"
import { PhotoMeta } from "@/components/portfolio/photo-meta"

const photos = [
  {
    seed: "fjord-dawn",
    alt: "A fjord under a pale midnight sun, mountains on both sides",
    note: "Hvalfjörður, an hour after midnight.",
    meta: { camera: "Fujifilm X-T5", lens: "XF 33mm F1.4", focal: 33, aperture: 2.8, shutter: "1/250", iso: 400, date: "2026-06-14" },
  },
  {
    seed: "basalt-coast",
    alt: "Dark basalt ridges above a quiet bay at dusk",
    note: "Reynisfjara, waiting out the rain.",
    meta: { camera: "Fujifilm X-T5", lens: "XF 16mm F2.8", focal: 16, aperture: 8, shutter: "1/60", iso: 200, date: "2026-06-16" },
  },
  {
    seed: "highland-road",
    alt: "Rolling highland hills under low cloud",
    note: "Route F35 through the highlands.",
    meta: { camera: "Fujifilm X100V", focal: 23, aperture: 5.6, shutter: "1/500", iso: 160, date: "2026-06-18" },
  },
] as const

export default function LightboxWithPhotoDetails() {
  return (
    <Lightbox label="Iceland, June" className="mx-auto grid w-full max-w-2xl grid-cols-3 gap-3 md:gap-4">
      {photos.map((photo) => (
        <LightboxTrigger
          key={photo.seed}
          alt={photo.alt}
          className="aspect-[4/5]"
          caption={
            <div className="flex flex-col items-center gap-1.5">
              <p className="text-foreground">{photo.note}</p>
              <PhotoMeta {...photo.meta} className="justify-center" />
            </div>
          }
        >
          <GenerativeArt seed={photo.seed} variant="landscape" />
        </LightboxTrigger>
      ))}
    </Lightbox>
  )
}
```

## API Reference

### Lightbox

Groups `<LightboxTrigger>`s — they can sit anywhere inside, at any depth (a grid, prose, cards) — and
renders the viewer. Items are browsed in document order. Renders a plain `<div>`, so lay the
triggers out with `className` or your own markup.

In the viewer, ← and → browse, Home and End jump to the first and last item, and Esc (the close
button, a click beside the media or a swipe down) puts the item back and returns focus to its
thumbnail. Focus stays inside the viewer while it's open, and the page behind doesn't scroll.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `React.ReactNode` | — | Your gallery markup; every `LightboxTrigger` inside becomes one item of the viewer, in document order. |
| `label` | `string` | `"Gallery"` | Accessible name of the viewer, also shown as its small label (e.g. the project name). |
| `labels` | `Partial<LightboxLabels>` | — | Built-in text (buttons, counter, loading and error states), for translations: `{ previous, next, close, position, loading, unavailable, unavailableName }`. |
| `loop` | `boolean` | `true` | Wrap from the last item to the first (and back). |
| `onOpenChange` | `(open: boolean) => void` | — | Called when the viewer opens or finishes closing. |
| `onIndexChange` | `(index: number) => void` | — | Called with the index (in document order) of the item on screen. |
| `viewerClassName` | `string` | — | Classes for the full-screen viewer (it renders in a portal, outside this element). |

Also accepts every `div` prop.

### LightboxGroup

`<Lightbox>` without its `<div>`: same props and viewer, no DOM of its own. Use it when the triggers'
container is your own element (a `<ul>`, a grid component) and an extra wrapper would get in the way.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Gallery"` | Accessible name of the viewer, also shown as its small label (e.g. the project name). |
| `labels` | `Partial<LightboxLabels>` | — | Built-in text (buttons, counter, loading and error states), for translations: `{ previous, next, close, position, loading, unavailable, unavailableName }`. |
| `loop` | `boolean` | `true` | Wrap from the last item to the first (and back). |
| `onOpenChange` | `(open: boolean) => void` | — | Called when the viewer opens or finishes closing. |
| `onIndexChange` | `(index: number) => void` | — | Called with the index (in document order) of the item on screen. |
| `viewerClassName` | `string` | — | Classes for the full-screen viewer (it renders in a portal, outside this element). |
| `children` | `React.ReactNode` | — | Your gallery markup; every `LightboxTrigger` inside becomes one item of the viewer, in document order. |

### LightboxTrigger

A thumbnail button that opens the viewer at this item. Put an `<img>`, `<GenerativeArt />` or any
artwork inside and size it with `className` (e.g. `aspect-[4/3]`); direct `<img>` children are cropped
to fill. Without `src` or `video`, the viewer shows the same artwork, larger.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alt` (required) | `string` | — | Describes what the media shows, as you'd tell someone who can't see it ("Tidewater dashboard on a wall display", not "image of dashboard"). Required: it's also the thumbnail button's name. |
| `src` | `string` | — | Full-size image URL. With no `children`, it's also the thumbnail. |
| `video` | `string` | — | Video URL. The viewer plays it with native controls; the thumbnail gets a play badge. |
| `poster` | `string` | — | Poster frame for `video`. |
| `captions` | `string` | — | WebVTT captions for `video`. |
| `caption` | `React.ReactNode` | — | Shown under the media in the viewer and announced as its description. Text or block content (a `<PhotoMeta>`, a short list). Without it, `alt` is the description. |
| `ratio` | `number` | — | Width ÷ height of the large view for artwork and video (e.g. `4 / 5`). Defaults to the thumbnail's own shape, so artwork grows without re-cropping. Images always use their natural ratio. |
| `content` | `React.ReactNode` | — | What to show large for artwork, if not the thumbnail itself (e.g. a more detailed `<GenerativeArt />`). |
| `zoom` | `boolean` | `true` | Scale the thumbnail's media on hover. Turn off when the children zoom themselves (e.g. `<Media zoom />`). |

Also accepts every `button` prop.

### type LightboxLabels

Built-in text of the viewer, for translations. `{index}`, `{count}` and `{alt}` are replaced.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `previous` (required) | `string` | — | Previous-item button. |
| `next` (required) | `string` | — | Next-item button. |
| `close` (required) | `string` | — | Close button. |
| `position` (required) | `string` | — | Position spoken with the counter and when browsing, e.g. "2 of 5". |
| `loading` (required) | `string` | — | Shown while a slow image loads. |
| `unavailable` (required) | `string` | — | Shown in place of an image that failed to load. |
| `unavailableName` (required) | `string` | — | Accessible name of that placeholder. |



---

# Link Preview

> An inline link that shows a small card (cover, title, description, site) on hover or keyboard focus; Escape closes it. On touch screens it's just a link.

Category: Content · Registry item: `@portfolio-kit/link-preview` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/link-preview) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/link-preview.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/link-preview
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/link-preview.tsx`.

npm dependencies: `lucide-react`, `radix-ui`.

## Usage

```tsx
import { LinkPreview } from "@/components/portfolio/link-preview"

<p>
  Right now I&rsquo;m building{" "}
  <LinkPreview
    href="https://example.com/lumen"
    heading="Lumen, the design system behind eleven products"
    description="Tokens, components and docs, shipped by a team of four."
    cover={<img src="/lumen-og.jpg" alt="" />}
  >
    Lumen
  </LinkPreview>
  .
</p>
```

## Examples

### Demo

Hover or tab to a link in a bio to see where it goes before you click.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { LinkPreview } from "@/components/portfolio/link-preview"

export default function LinkPreviewDemo() {
  return (
    <p className="mx-auto w-full max-w-lg pt-4 text-lg leading-relaxed text-pretty text-muted-foreground">
      I&rsquo;m a design engineer in Lisbon. Right now I&rsquo;m building{" "}
      <LinkPreview
        href="https://example.com/lumen"
        // Open on load so the preview is visible here; drop this in your app.
        defaultOpen
        heading="Lumen — the design system behind eleven products"
        description="Tokens, components and docs for Halcyon Labs, shipped by a team of four."
        cover={<GenerativeArt seed="lumen" variant="interface" />}
      >
        Lumen
      </LinkPreview>{" "}
      and writing about{" "}
      <LinkPreview
        href="https://example.com/notes/motion-with-intent"
        heading="Motion with intent"
        description="Animation should answer a question the user just asked. A field guide to motion that informs."
        site="Notes · 7 min read"
        cover={<GenerativeArt seed="motion-with-intent" variant="interface" />}
      >
        motion that informs
      </LinkPreview>
      .
    </p>
  )
}
```

### In an article

Text-only previews for internal links in running prose: no cover, a custom `site` label, and a quicker `openDelay` for readers who skim.

```tsx
import { LinkPreview } from "@/components/portfolio/link-preview"
import { Prose } from "@/components/portfolio/prose"

export default function LinkPreviewTextOnly() {
  return (
    <Prose className="mx-auto pt-4">
      <p>
        I wrote about this in{" "}
        <LinkPreview
          href="/notes/tokens-are-an-api"
          heading="Tokens are an API"
          description="Semver, deprecation windows and codemods kept eleven product teams shipping."
          site="Notes · Dec 2025 · 11 min read"
          openDelay={250}
        >
          Tokens are an API
        </LinkPreview>
        , and the short version is in the{" "}
        <LinkPreview
          href="/uses"
          heading="Uses"
          description="The hardware, apps and fonts I work with every day."
          site="Page"
          openDelay={250}
        >
          uses page
        </LinkPreview>
        .
      </p>
    </Prose>
  )
}
```

### Custom card

Pass `preview` to build your own card from the `LinkPreview*` parts — here, repository stats for the open-source projects a developer mentions in their bio.

```tsx
import { Scale, Star } from "lucide-react"

import { BrandIcon } from "@/components/portfolio/brand-icons"
import {
  LinkPreview,
  LinkPreviewDescription,
  LinkPreviewHeading,
  LinkPreviewSite,
} from "@/components/portfolio/link-preview"

type Repo = {
  owner: string
  name: string
  description: string
  language: string
  /** GitHub's language color: data, not a theme color. */
  color: string
  stars: string
  license: string
}

function RepoPreview({ repo }: { repo: Repo }) {
  return (
    <div className="flex flex-col gap-1.5 p-4">
      <p className="flex items-center gap-2 font-mono text-xs text-muted-foreground">
        <BrandIcon name="github" className="size-3.5" />
        {repo.owner}/{repo.name}
      </p>
      <LinkPreviewHeading>{repo.name}</LinkPreviewHeading>
      <LinkPreviewDescription>{repo.description}</LinkPreviewDescription>
      <LinkPreviewSite className="gap-4">
        <span className="flex items-center gap-1.5">
          <span className="size-2.5 rounded-full" style={{ backgroundColor: repo.color }} />
          {repo.language}
        </span>
        <span className="flex items-center gap-1 tabular-nums">
          <Star aria-hidden className="size-3.5" />
          {repo.stars}
        </span>
        <span className="flex items-center gap-1">
          <Scale aria-hidden className="size-3.5" />
          {repo.license}
        </span>
      </LinkPreviewSite>
    </div>
  )
}

const tidal: Repo = {
  owner: "example",
  name: "tidal",
  description: "A 2 kB scheduler that batches DOM reads and writes into one animation frame.",
  language: "TypeScript",
  color: "#3178c6",
  stars: "2.4k",
  license: "MIT",
}

const kiln: Repo = {
  owner: "example",
  name: "kiln",
  description: "Turns a folder of design tokens into CSS, Swift and Kotlin in one command.",
  language: "Rust",
  color: "#dea584",
  stars: "860",
  license: "Apache-2.0",
}

export default function LinkPreviewCustomCard() {
  return (
    <p className="mx-auto w-full max-w-lg pt-4 text-lg leading-relaxed text-pretty text-muted-foreground">
      By day I build front-end infrastructure. By night I maintain{" "}
      <LinkPreview
        href="https://github.com/example/tidal"
        // Open on load so the preview is visible here; drop this in your app.
        defaultOpen
        preview={<RepoPreview repo={tidal} />}
      >
        tidal
      </LinkPreview>
      , a tiny frame scheduler, and{" "}
      <LinkPreview href="https://github.com/example/kiln" preview={<RepoPreview repo={kiln} />}>
        kiln
      </LinkPreview>
      , a token compiler used by a few design teams.
    </p>
  )
}
```

## API Reference

### LinkPreview

A real `<a>` with a preview card. The card opens after `openDelay` on hover or keyboard focus,
stays while the pointer is over it, and closes on Escape, blur or pointer leave. It never takes
focus and is purely supplementary: it's hidden from assistive tech and never opens for touch, so
a tap follows the link and the link always works on its own. External links show ↗. Add
`description` text to the link's `title` yourself if you want it available everywhere.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` (required) | `string` | — | Where the link goes. Absolute URLs open in a new tab. |
| `heading` | `React.ReactNode` | — | Title shown in the card, e.g. the page's `og:title`. |
| `description` | `React.ReactNode` | — | One or two lines about the page. Clamped to three lines. |
| `cover` | `React.ReactNode` | — | Cover for the card: an `<img>`, `<Media>` or `<GenerativeArt>`. Shown at the Open Graph ratio (1.91:1). |
| `site` | `React.ReactNode` | — | Small label under the text. Defaults to the link's hostname for absolute URLs. |
| `preview` | `React.ReactNode` | — | Replace the whole card body with your own content (compose it from the `LinkPreview*` parts). |
| `openDelay` | `number` | `450` | Hover time before the card opens, in ms. Keep it long enough that reading across a paragraph doesn't flash cards. |
| `closeDelay` | `number` | `150` | Time the card stays after the pointer leaves, in ms, so it can be reached with the mouse. |
| `side` | `"top" \| "bottom"` | `"bottom"` | Preferred side of the link to show the card on. It flips when there's no room. |
| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment of the card against the link. |
| `cardClassName` | `string` | — | Class names for the floating card surface. |
| `open` | `boolean` | — | Controlled open state of the card. |
| `defaultOpen` | `boolean` | — | Open state on first render (uncontrolled), e.g. to show the card in a screenshot or walkthrough. |
| `onOpenChange` | `(open: boolean) => void` | — | Called when the card opens or closes. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to links that open in a new tab. Translate it here. |

Also accepts every `a` prop.

### LinkPreviewMedia

Cover slot at the Open Graph ratio. Direct `<img>`/`<video>` children are cropped to fill.

Also accepts every `div` prop.

### LinkPreviewHeading

The page title.

Also accepts every `p` prop.

### LinkPreviewDescription

A short summary, clamped to three lines.

Also accepts every `p` prop.

### LinkPreviewSite

Mono site label (hostname, publication or date) under the text.

Also accepts every `p` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)



---

# Local Time

> Live clock for your city (“Lisbon 14:32 GMT+1”) with a day/night icon and an optional blinking colon.

Category: Hero · Registry item: `@portfolio-kit/local-time` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/local-time) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/local-time.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/local-time
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/local-time.tsx` and the kit items it uses: `use-local-time`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import { LocalTime, localTimeVariants } from "@/components/portfolio/local-time"
```

## Examples

### Demo

A live clock for where you work, so international clients know when to expect a reply. The icon flips to a moon at night.

```tsx
import { LocalTime } from "@/components/portfolio/local-time"
import { typography } from "@/lib/typography"

export default function LocalTimeDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col items-start gap-3">
      <p className={typography.eyebrow}>Working hours</p>
      <p className="text-pretty text-muted-foreground">
        I work Monday to Friday, roughly 9 to 6 in Lisbon, and reply to every email within a working day.
      </p>
      <LocalTime timeZone="Europe/Lisbon" variant="pill" />
    </div>
  )
}
```

### Team Clocks

One clock per studio or teammate. The city name comes from the IANA zone, or pass your own with `city`.

```tsx
import { LocalTime } from "@/components/portfolio/local-time"
import { typography } from "@/lib/typography"

const studios = [
  { timeZone: "Europe/Lisbon", team: "Design" },
  { timeZone: "America/New_York", team: "Engineering" },
  { timeZone: "Asia/Tokyo", team: "Research" },
  { timeZone: "America/Los_Angeles", city: "San Francisco", team: "Support" },
]

export default function LocalTimeWorldClocks() {
  return (
    <ul role="list" className="w-full max-w-sm divide-y border-y">
      {studios.map((studio) => (
        <li key={studio.timeZone} className="flex items-center justify-between gap-4 py-3">
          <LocalTime timeZone={studio.timeZone} city={studio.city} />
          <span className={typography.meta}>{studio.team}</span>
        </li>
      ))}
    </ul>
  )
}
```

### In a Sentence

The inline variant reads as part of the copy, e.g. in a contact section or an about blurb.

```tsx
import { LocalTime } from "@/components/portfolio/local-time"

export default function LocalTimeInASentence() {
  return (
    <p className="w-full max-w-md text-lg leading-relaxed text-pretty text-muted-foreground">
      I work from <LocalTime timeZone="Europe/Lisbon" className="text-foreground" /> and usually reply within a day.
    </p>
  )
}
```

### Options

Seconds, a 12-hour clock, no icon or no city. Half-hour zones like India (GMT+5:30) work too.

```tsx
import { LocalTime } from "@/components/portfolio/local-time"

export default function LocalTimeOptions() {
  return (
    <div className="flex flex-col items-start gap-4">
      <LocalTime timeZone="Europe/Lisbon" variant="pill" seconds />
      <LocalTime timeZone="America/Los_Angeles" variant="pill" hour12 />
      <LocalTime timeZone="Europe/Berlin" icon={false} offset={false} />
      <LocalTime timeZone="Asia/Kolkata" city={false} blink={false} />
    </div>
  )
}
```

## API Reference

### LocalTime

A live clock for a time zone: day/night icon, place, time and GMT offset. `inline` reads as part
of a sentence or meta row, `pill` stands on its own over heroes and media. SSR-safe: until the
browser takes over it shows `--:--` (same width), so a cached or static page never shows a stale
time or a hydration mismatch. An unknown zone falls back to UTC.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `timeZone` (required) | `string` | — | IANA time zone, e.g. "Europe/Lisbon". |
| `variant` | `"inline" \| "pill"` | `"inline"` | `inline`: text that sits in a sentence or a meta row. `pill`: a bordered chip, for heroes and headers. |
| `city` | `string \| false` | — | Place name shown before the time. Defaults to the zone's city ("Europe/New_York" → "New York"). Pass `false` to hide. |
| `seconds` | `boolean` | `false` | Show seconds (the clock then ticks every second instead of every minute). |
| `hour12` | `boolean` | — | 12-hour clock ("02:32 PM") instead of 24-hour. |
| `blink` | `boolean` | — | Blink the colon(s) a few times, then hold them (under 5 s, so it needs no pause control under WCAG 2.2.2). Defaults to on for a live clock, off when `now` freezes it. Off for reduced motion. |
| `offset` | `boolean` | `true` | Show the GMT offset. |
| `icon` | `boolean` | `true` | Show the sun / moon icon. |
| `now` | `Date` | — | Freeze the clock (tests, screenshots). Without it, the server renders a placeholder (`--:--`) that the browser replaces with the live time after hydration. |
| `locale` | `string` | `"en-US"` | BCP 47 locale for the time format, e.g. `"en-GB"`. Fixed rather than the browser's, so server and client agree. |
| `timeLabel` | `string` | `"local time"` | Screen-reader words between the place and the time ("Lisbon local time 14:32"). Translate it here. |

Also accepts every `span` prop.

## Used in templates

- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Location Tag

> “Based in Lisbon, Portugal” with a map pin, optional coordinates in mono and an optional link to a map.

Category: Hero · Registry item: `@portfolio-kit/location-tag` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/location-tag) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/location-tag.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/location-tag
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/location-tag.tsx`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import { LocationTag, locationTagVariants, formatCoordinates } from "@/components/portfolio/location-tag"
```

## Examples

### Demo

“Based in…” with a pin and optional coordinates in mono, for a hero or about section.

```tsx
import { LocationTag } from "@/components/portfolio/location-tag"

export default function LocationTagDemo() {
  return (
    <div className="flex w-full max-w-md flex-col items-start gap-4">
      <LocationTag location="Lisbon, Portugal" coordinates={[38.7223, -9.1393]} />
      <p className="font-heading text-3xl leading-tight text-balance">Design engineer building calm, fast interfaces.</p>
    </div>
  )
}
```

### Linked Pill

With `href` the tag links to a map. The pill lifts on hover and external URLs open in a new tab.

```tsx
import { LocationTag } from "@/components/portfolio/location-tag"

export default function LocationTagLinkedPill() {
  return (
    <LocationTag
      variant="pill"
      location="Lisbon"
      coordinates={[38.7223, -9.1393]}
      href="https://maps.example.com/?q=Lisbon"
    />
  )
}
```

### Variations

Change or drop the prefix, hide the pin and set the coordinate precision. Southern and western hemispheres are handled.

```tsx
import { LocationTag } from "@/components/portfolio/location-tag"

export default function LocationTagVariations() {
  return (
    <div className="flex flex-col items-start gap-4">
      <LocationTag prefix="Working from" location="Lisbon" href="#contact" />
      <LocationTag prefix={null} location="Cape Town" coordinates={[-33.9249, 18.4241]} precision={1} />
      <LocationTag variant="pill" prefix={null} location="Wellington, NZ" coordinates={[-41.2865, 174.7762]} />
      <LocationTag variant="pill" icon={false} prefix="Remote," location="GMT+1" />
    </div>
  )
}
```

### Hero Meta Row

Next to Local Time and an Availability Badge, as the meta row at the bottom of a hero.

```tsx
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { LocalTime } from "@/components/portfolio/local-time"
import { LocationTag } from "@/components/portfolio/location-tag"

export default function LocationTagMetaRow() {
  return (
    <div className="mx-auto flex max-w-5xl flex-wrap items-center justify-between gap-x-8 gap-y-4 border-t pt-5 text-sm">
      <LocationTag location="Lisbon, Portugal" coordinates={[38.7223, -9.1393]} />
      <LocalTime timeZone="Europe/Lisbon" />
      <AvailabilityBadge variant="plain">Taking projects</AvailabilityBadge>
    </div>
  )
}
```

## API Reference

### LocationTag

Pin, "Based in" prefix, place and optional coordinates. Renders a `<span>`, or an `<a>` when
you pass `href` (e.g. a map link). `inline` sits in meta rows and copy, `pill` stands on its own.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `location` (required) | `React.ReactNode` | — | Place name, e.g. "Lisbon, Portugal". |
| `href` | `string` | — | Link to a map. External URLs open in a new tab and say so to screen readers. |
| `variant` | `"inline" \| "pill"` | `"inline"` | `inline`: pin and text that sit in a sentence or a meta row. `pill`: a bordered chip, for heroes and headers. |
| `prefix` | `React.ReactNode` | `"Based in"` | Muted text before the place. Pass `null` to hide. |
| `coordinates` | `Coordinates` | — | `[lat, lng]` rendered as "38.72° N, 9.14° W" and read out as "38.72° north, 9.14° west". |
| `precision` | `number` | `2` | Decimal places for coordinates (`2` ≈ 1 km, `1` ≈ 10 km). |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added when `href` opens in a new tab. Translate it here. |
| `icon` | `boolean` | `true` | Show the pin icon. |
| `labels` | `Partial<LocationTagLabels>` | — | Spoken hemisphere names for the coordinates: `{ north, south, east, west }`. Translate them here. |

Also accepts every `a` prop.

### type LocationTagLabels

Spoken hemisphere names; the visible coordinates keep the letters N, S, E and W.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `north` (required) | `string` | — |  |
| `south` (required) | `string` | — |  |
| `east` (required) | `string` | — |  |
| `west` (required) | `string` | — |  |

## Used in templates

- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)



---

# Logo Cloud

> Client logos or wordmarks as a bordered grid, a wrapping row or an endless marquee with a pause button. Muted by default, full color on hover.

Category: Social Proof · Registry item: `@portfolio-kit/logo-cloud` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/logo-cloud) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/logo-cloud.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/logo-cloud
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/logo-cloud.tsx` and the kit items it uses: `marquee`, `typography`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  Logo,
  LogoCloud,
  LogoCloudHeading,
  LogoCloudList,
} from "@/components/portfolio/logo-cloud"

<LogoCloud>
  <LogoCloudHeading />
  <LogoCloudList>
    <Logo>Halcyon</Logo>
    <Logo>Northpeak</Logo>
    <Logo>Tidewater</Logo>
  </LogoCloudList>
</LogoCloud>
```

## Examples

### Demo

A bordered “trusted by” grid of client wordmarks, muted until hovered so they support the page instead of competing with it.

```tsx
import type * as React from "react"

import { Logo, LogoCloud, LogoCloudHeading, LogoCloudList } from "@/components/portfolio/logo-cloud"

/** Fictional clients. Swap the text wordmarks for their SVG logos. */
const clients: Array<{ name: string; mark: React.ReactNode }> = [
  { name: "Halcyon", mark: <span className="font-heading text-2xl">Halcyon</span> },
  { name: "Tidewater", mark: <span className="font-mono text-base font-semibold tracking-[0.22em] uppercase">Tidewater</span> },
  { name: "Fieldnote", mark: <span className="font-serif text-2xl italic">Fieldnote</span> },
  {
    name: "Orbit",
    mark: (
      <span className="flex items-center gap-2 text-xl font-semibold tracking-tight">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" aria-hidden className="h-6!">
          <circle cx="12" cy="12" r="9" />
          <circle cx="12" cy="12" r="3" fill="currentColor" stroke="none" />
        </svg>
        orbit
      </span>
    ),
  },
  { name: "Kiln", mark: <span className="text-3xl font-black tracking-tighter lowercase">kiln.</span> },
  { name: "Meridian", mark: <span className="text-lg font-light tracking-[0.4em] uppercase">Meridian</span> },
  {
    name: "Northpeak",
    mark: (
      <span className="flex items-center gap-1.5 text-lg font-bold tracking-tight">
        <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden className="h-5!">
          <path d="M12 3 2 21h20L12 3Zm0 6.5 3.6 6.5H8.4L12 9.5Z" />
        </svg>
        NORTHPEAK
      </span>
    ),
  },
  {
    name: "Atlas & Co",
    mark: (
      <span className="font-serif text-2xl">
        Atlas <span className="italic">&amp;</span> Co
      </span>
    ),
  },
]

export default function LogoCloudDemo() {
  return (
    <LogoCloud className="mx-auto max-w-5xl">
      <LogoCloudHeading />
      <LogoCloudList>
        {clients.map((client) => (
          <Logo key={client.name} name={client.name}>
            {client.mark}
          </Logo>
        ))}
      </LogoCloudList>
    </LogoCloud>
  )
}
```

### Inline

A centered, wrapping row without borders. The lightest way to add social proof under a hero.

```tsx
import type * as React from "react"

import { Logo, LogoCloud, LogoCloudHeading, LogoCloudList } from "@/components/portfolio/logo-cloud"

const clients: Array<{ name: string; mark: React.ReactNode }> = [
  { name: "Halcyon", mark: <span className="font-heading text-2xl">Halcyon</span> },
  { name: "Tidewater", mark: <span className="font-mono text-base font-semibold tracking-[0.22em] uppercase">Tidewater</span> },
  { name: "Fieldnote", mark: <span className="font-serif text-2xl italic">Fieldnote</span> },
  { name: "Kiln", mark: <span className="text-3xl font-black tracking-tighter lowercase">kiln.</span> },
  { name: "Meridian", mark: <span className="text-lg font-light tracking-[0.4em] uppercase">Meridian</span> },
]

export default function LogoCloudInline() {
  return (
    <LogoCloud variant="inline" className="mx-auto max-w-4xl">
      <LogoCloudHeading>Clients I&apos;ve shipped with</LogoCloudHeading>
      <LogoCloudList>
        {clients.map((client) => (
          <Logo key={client.name} name={client.name}>
            {client.mark}
          </Logo>
        ))}
      </LogoCloudList>
    </LogoCloud>
  )
}
```

### Marquee

An endless, edge-to-edge ticker for client lists too long to wrap neatly, with a pause button below it; it stands still under reduced motion.

```tsx
import type * as React from "react"

import { Logo, LogoCloud, LogoCloudHeading, LogoCloudList } from "@/components/portfolio/logo-cloud"

const clients: Array<{ name: string; mark: React.ReactNode }> = [
  { name: "Halcyon", mark: <span className="font-heading text-2xl">Halcyon</span> },
  { name: "Tidewater", mark: <span className="font-mono text-base font-semibold tracking-[0.22em] uppercase">Tidewater</span> },
  { name: "Fieldnote", mark: <span className="font-serif text-2xl italic">Fieldnote</span> },
  { name: "Kiln", mark: <span className="text-3xl font-black tracking-tighter lowercase">kiln.</span> },
  { name: "Meridian", mark: <span className="text-lg font-light tracking-[0.4em] uppercase">Meridian</span> },
  {
    name: "Atlas & Co",
    mark: (
      <span className="font-serif text-2xl">
        Atlas <span className="italic">&amp;</span> Co
      </span>
    ),
  },
]

export default function LogoCloudMarquee() {
  return (
    <LogoCloud variant="marquee" className="py-12 md:py-16">
      <LogoCloudHeading>Selected clients, 2016 — now</LogoCloudHeading>
      <LogoCloudList duration={45}>
        {clients.map((client) => (
          <Logo key={client.name} name={client.name}>
            {client.mark}
          </Logo>
        ))}
      </LogoCloudList>
    </LogoCloud>
  )
}
```

### Linked Grid

Each logo links to its case study (the whole cell is clickable), with a count beside the heading.

```tsx
import type * as React from "react"

import { Logo, LogoCloud, LogoCloudHeading, LogoCloudList } from "@/components/portfolio/logo-cloud"
import { typography } from "@/lib/typography"

const clients: Array<{ slug: string; name: string; mark: React.ReactNode }> = [
  { slug: "halcyon", name: "Halcyon", mark: <span className="font-heading text-2xl">Halcyon</span> },
  {
    slug: "tidewater",
    name: "Tidewater",
    mark: <span className="font-mono text-base font-semibold tracking-[0.22em] uppercase">Tidewater</span>,
  },
  { slug: "fieldnote", name: "Fieldnote", mark: <span className="font-serif text-2xl italic">Fieldnote</span> },
  { slug: "kiln", name: "Kiln", mark: <span className="text-3xl font-black tracking-tighter lowercase">kiln.</span> },
  { slug: "meridian", name: "Meridian", mark: <span className="text-lg font-light tracking-[0.4em] uppercase">Meridian</span> },
  {
    slug: "atlas",
    name: "Atlas & Co",
    mark: (
      <span className="font-serif text-2xl">
        Atlas <span className="italic">&amp;</span> Co
      </span>
    ),
  },
]

export default function LogoCloudLinked() {
  return (
    <LogoCloud className="mx-auto max-w-5xl">
      <div className="flex flex-wrap items-end justify-between gap-4">
        <LogoCloudHeading>Clients &amp; collaborators</LogoCloudHeading>
        <p className={typography.meta}>6 case studies · 4 countries</p>
      </div>
      <LogoCloudList columns={3}>
        {clients.map((client) => (
          <Logo key={client.slug} href={`#${client.slug}`} name={client.name}>
            {client.mark}
          </Logo>
        ))}
      </LogoCloudList>
    </LogoCloud>
  )
}
```

## API Reference

### LogoCloud

Root wrapper. Holds an optional `LogoCloudHeading` and a `LogoCloudList` of `Logo`s.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"grid" \| "inline" \| "marquee"` | `"grid"` | `grid`: bordered cells. `inline`: a centered, wrapping row. `marquee`: an endless ticker with a pause button; it also pauses on hover and while a logo link has focus, and stands still (one centered, wrapping row) under reduced motion. |

Also accepts every `div` prop.

### LogoCloudHeading

Small label above the logos. Defaults to "Trusted by teams at".

Also accepts every `p` prop.

### LogoCloudList

The logos, a `<ul>` labelled `label`. `columns` sets the grid's widest column count (it steps
down to 2 on mobile). In the `marquee` variant the list loops inside a `Marquee`, with a pause
button below it; only the first copy is exposed to assistive tech and the keyboard.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `2 \| 3 \| 4 \| 5 \| 6` | `4` | Grid columns on wide screens (`grid` variant only); phones show two. Pick a divisor of your logo count so the last row is full. |
| `label` | `string` | `"Clients"` | Accessible name of the list. |
| `duration` | `number` | `40` | Marquee only: seconds per loop. Lower is faster. |
| `reverse` | `boolean` | — | Marquee only: scroll the other way. |
| `pauseLabel` | `string` | `"Pause logos"` | Marquee only: accessible name of the pause button (a toggle, pressed while paused). |

Also accepts every `ul` prop.

### Logo

One client. Children: an `<svg>`, `<img>` or a text wordmark. Images and SVGs are sized to the row
height and never wider than their cell. Muted and grayscale until hovered. Draw SVG logos with
`currentColor` so they follow the theme in dark mode; for a raster logo, pass a light and a dark file
(`<img className="dark:hidden" />` and `<img className="hidden dark:block" />`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | Link to the client or case study. In the grid the whole cell becomes clickable. Absolute URLs open in a new tab. |
| `name` | `string` | — | Accessible name. Required when the children are an image or SVG without text; for a styled wordmark it reads better than the raw text ("Kiln", not "kiln."). |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to links that open in a new tab. Translate it here. |

Also accepts every `li` prop.

## Used in templates

- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Magnetic

> Pulls a button or icon toward a nearby pointer and springs back when it leaves. An optional inner layer moves further for depth.

Category: Effects · Registry item: `@portfolio-kit/magnetic` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/magnetic) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/magnetic.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/magnetic
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/magnetic.tsx` and the kit items it uses: `use-composed-refs`, `use-fine-pointer`, `use-reduced-motion`.

npm dependencies: `radix-ui`.

## Usage

```tsx
import {
  Magnetic,
  MagneticInner,
} from "@/components/portfolio/magnetic"

<Magnetic strength={0.4} padding={40}>
  <a href="#contact">
    <MagneticInner>Get in touch</MagneticInner>
  </a>
</Magnetic>
```

## Examples

### Demo

A round “Get in touch” button that leans out of its ring toward the pointer, with its label on a `MagneticInner` layer that travels further for depth.

```tsx
import { ArrowUpRight } from "lucide-react"

import { cn } from "@/lib/utils"
import { Magnetic, MagneticInner } from "@/components/portfolio/magnetic"
import { typography } from "@/lib/typography"

export default function MagneticDemo() {
  return (
    <div className="flex flex-col items-center gap-10 py-10">
      <div className="relative grid place-items-center">
        {/* The resting place: a fixed ring the button leans out of as the pointer comes near. */}
        <span aria-hidden className="absolute size-48 rounded-full border bg-muted md:size-56" />
        <Magnetic strength={0.4} padding={40}>
          <a
            href="#contact"
            className="group relative isolate inline-flex size-40 items-center justify-center overflow-hidden rounded-full bg-foreground text-background outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 md:size-48"
          >
            {/* Highlight fill that rises from the bottom on hover. */}
            <span
              aria-hidden
              className="absolute inset-0 -z-10 translate-y-full rounded-full bg-highlight transition-transform duration-500 ease-smooth group-focus-visible:translate-y-0 motion-reduce:transition-none [@media(hover:hover)]:group-hover:translate-y-0"
            />
            <MagneticInner className="flex-col gap-1.5 font-heading text-lg transition-colors duration-300 group-focus-visible:text-highlight-foreground md:text-xl [@media(hover:hover)]:group-hover:text-highlight-foreground">
              Get in touch
              <ArrowUpRight
                aria-hidden
                className="size-5 transition-transform duration-500 ease-smooth motion-reduce:transition-none [@media(hover:hover)]:group-hover:rotate-45"
              />
            </MagneticInner>
          </a>
        </Magnetic>
      </div>
      {/* Only where the pull runs: hidden on touch screens and with reduced motion. */}
      <p className={cn(typography.meta, "[@media(hover:none)]:hidden [@media(pointer:coarse)]:hidden motion-reduce:hidden")}>Move your pointer near the button</p>
    </div>
  )
}
```

### Social icons

Icon buttons in a footer or contact row. Neighbours need a lighter pull and a short reach so they never bump into each other.

```tsx
import { Mail } from "lucide-react"

import { cn } from "@/lib/utils"
import { BrandIcon, type BrandName } from "@/components/portfolio/brand-icons"
import { Magnetic, MagneticInner } from "@/components/portfolio/magnetic"
import { typography } from "@/lib/typography"

const socials: { brand: BrandName; label: string; href: string }[] = [
  { brand: "github", label: "GitHub", href: "https://github.com/example" },
  { brand: "x", label: "X", href: "https://x.com/example" },
  { brand: "dribbble", label: "Dribbble", href: "https://dribbble.com/example" },
]

const iconButton =
  "inline-flex size-12 items-center justify-center rounded-pill outline-none transition-colors duration-200 focus-visible:ring-[3px] focus-visible:ring-ring/50"

export default function MagneticSocialIcons() {
  return (
    <div className="flex flex-col items-center gap-8 py-6">
      <ul role="list" className="flex items-center gap-4" aria-label="Social links">
        {socials.map((social) => (
          <li key={social.brand}>
            <Magnetic strength={0.2} padding={8}>
              <a
                href={social.href}
                aria-label={`${social.label} (opens in a new tab)`}
                target="_blank"
                rel="noopener noreferrer"
                className={cn(iconButton, "border bg-background text-muted-foreground shadow-card hover:border-border-hover hover:text-foreground")}
              >
                <MagneticInner>
                  <BrandIcon name={social.brand} className="size-[1.1rem]" />
                </MagneticInner>
              </a>
            </Magnetic>
          </li>
        ))}
        <li>
          <Magnetic strength={0.2} padding={8}>
            <a
              href="mailto:hello@example.com"
              aria-label="Email"
              className={cn(iconButton, "bg-foreground text-background hover:bg-highlight hover:text-highlight-foreground")}
            >
              <MagneticInner>
                <Mail aria-hidden className="size-[1.1rem]" />
              </MagneticInner>
            </a>
          </Magnetic>
        </li>
      </ul>
      <p className={cn(typography.meta, "[@media(hover:none)]:hidden [@media(pointer:coarse)]:hidden motion-reduce:hidden")}>Move your pointer along the icons</p>
    </div>
  )
}
```

### Call to action

Two pill buttons side by side. The primary pulls harder than the secondary, and a small `padding` with a wide gap keeps their reach from overlapping.

```tsx
import { ArrowRight } from "lucide-react"

import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import { Magnetic, MagneticInner } from "@/components/portfolio/magnetic"
import {
  SectionActions,
  SectionDescription,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

export default function MagneticCta() {
  return (
    <div className="mx-auto flex max-w-3xl flex-col gap-10 py-10 md:py-16">
      <SectionHeader align="center">
        <SectionTitle>Have a project in mind?</SectionTitle>
        <SectionDescription>
          I take on two or three projects a quarter. Tell me what you&rsquo;re building and I&rsquo;ll reply within
          two working days.
        </SectionDescription>
      </SectionHeader>
      <SectionActions className="justify-center gap-8">
        <Magnetic strength={0.25} padding={12} innerStrength={1.3}>
          <a href="#contact" className={buttonVariants({ size: "lg", className: "h-12 rounded-pill px-7" })}>
            <MagneticInner>
              Start a project
              <ArrowRight aria-hidden className="size-4" />
            </MagneticInner>
          </a>
        </Magnetic>
        <Magnetic strength={0.15} padding={12} innerStrength={1.3}>
          <a
            href="#work"
            className={buttonVariants({ variant: "outline", size: "lg", className: "h-12 rounded-pill px-7" })}
          >
            <MagneticInner>See the work</MagneticInner>
          </a>
        </Magnetic>
      </SectionActions>
      <p className={cn(typography.meta, "text-center [@media(hover:none)]:hidden [@media(pointer:coarse)]:hidden motion-reduce:hidden")}>Move your pointer toward the buttons</p>
    </div>
  )
}
```

## API Reference

### Magnetic

Wrap a button, link or icon. The pull only runs on devices with a fine pointer
and is skipped under reduced motion, so the element stays put on touch screens.
Keyboard focus doesn't move it. Movement is a transform on this element, so layout is untouched.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `strength` | `number` | `0.35` | How far the element follows the pointer, as a fraction of the pointer's offset from its center (0–1, clamped). The element never travels past the pointer, so it stays under it and clicks land. |
| `padding` | `number` | `24` | Extra reach around the element's bounds, in px, where the pull starts. For a row of magnetic buttons keep it under half the gap so neighbours don't collide. |
| `innerStrength` | `number` | `1.6` | Multiplier for `<MagneticInner>` layers relative to the element (1.6 = moves 60% further). |
| `stiffness` | `number` | `0.14` | Spring stiffness (0–1). Higher snaps toward the pointer faster. |
| `damping` | `number` | `0.72` | Share of velocity kept each frame (0–1). Higher overshoots and wobbles more; lower settles without bounce. |
| `disabled` | `boolean` | `false` | Turn the pull off (e.g. while a menu is open) without unmounting. |
| `asChild` | `boolean` | — | Merge onto the single child instead of wrapping it in a div. |

Also accepts every `div` prop.

### MagneticInner

A layer inside `<Magnetic>` that travels further than its parent, for a sense of depth.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` | — | Merge onto the single child (e.g. an icon) instead of wrapping it in a span. |

Also accepts every `span` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)



---

# Marker

> Hand-drawn highlights, underlines, circles, boxes and strikes for key words in a bio or headline, drawn on when they scroll into view.

Category: Utilities · Registry item: `@portfolio-kit/marker` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/marker) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/marker.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/marker
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/marker.tsx` and the kit items it uses: `use-composed-refs`, `use-in-view`, `use-mount-check`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { Marker, MarkerGroup } from "@/components/portfolio/marker"

<MarkerGroup as="p">
  I design <Marker>calm interfaces</Marker> for <Marker variant="underline">complicated tools</Marker>.
</MarkerGroup>
```

## Examples

### Demo

A short bio where the words that matter get a highlighter stroke and a pen underline, drawn in turn as it scrolls into view.

```tsx
import { Marker, MarkerGroup } from "@/components/portfolio/marker"
import { typography } from "@/lib/typography"

export default function MarkerDemo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <p className={typography.eyebrow}>About</p>
      <MarkerGroup as="p" className={typography.lead}>
        I&apos;m Mara, a product designer in Lisbon. For eight years I&apos;ve helped teams turn{" "}
        <Marker>complicated tools into calm ones</Marker>, most recently at a climate-data startup where I led the{" "}
        <Marker variant="underline">design system</Marker>.
      </MarkerGroup>
    </div>
  )
}
```

### Annotated paragraph

Every style in one sequenced group: a struck-out old claim, a boxed number, a quiet foreground highlight and a quote marked with `<mark>`.

```tsx
import { Marker, MarkerGroup } from "@/components/portfolio/marker"
import { typography } from "@/lib/typography"

export default function MarkerAnnotations() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <MarkerGroup as="p" stagger={450} className={typography.body}>
        The plan said <Marker variant="strike">six weeks</Marker>; the redesign took three months. It cut support
        tickets by <Marker variant="box">41%</Marker> and, more importantly, it made the onboarding{" "}
        <Marker tone="foreground">feel like a conversation</Marker> instead of a form.
      </MarkerGroup>
      <blockquote className="border-l-2 pl-4 text-sm leading-relaxed text-pretty text-foreground md:text-base">
        &ldquo;Mara found the <Marker as="mark">three screens nobody had looked at in a year</Marker> and fixed them
        first.&rdquo;
      </blockquote>
    </div>
  )
}
```

### Circled headline

A hero statement with one word circled by hand. Circles and boxes stay on one line, so wrap a word or two.

```tsx
import { Marker } from "@/components/portfolio/marker"
import { Section } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

export default function MarkerHeadline() {
  return (
    <Section>
      <h1 className={typography.display}>
        Interfaces that feel <Marker variant="circle" duration={900} delay={200}>obvious</Marker> the second time.
      </h1>
      <p className={`${typography.lead} mt-6 max-w-xl`}>
        Independent designer working with small teams on products people open every day.
      </p>
    </Section>
  )
}
```

## API Reference

### Marker

Marks a run of text. It draws on once it passes a line 15% above the bottom of the viewport, or once
it is wholly visible (a short line at the very end of a page). With reduced motion, without
JavaScript and in print the mark is shown fully drawn; a mark the server HTML already drew before
the page hydrated stays drawn. Inside a `MarkerGroup` it draws in turn with its siblings once the
group is in view.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"highlight" \| "foreground"` | `"highlight"` | `highlight` uses the theme accent (the fill is tinted so text stays readable). `foreground` is a quiet ink version. |
| `variant` | `"highlight" \| "underline" \| "circle" \| "box" \| "strike"` | `"highlight"` | `highlight`: a highlighter stroke behind the text. `underline` and `strike`: a pen line under (clear of descenders) or through it. These three wrap across lines. `circle` and `box`: a hand-drawn outline around a short phrase that stays on one line. |
| `as` | `"span" \| "mark" \| "strong" \| "em" \| "s" \| "del" \| "ins"` | — | Element to render. Defaults to `<s>` for `strike` (the text is no longer accurate) and `<span>` otherwise. Use `mark` for a passage highlighted for reference (a quote, a search hit), `strong` or `em` when the words matter in the sentence too. The drawing itself is never announced. |
| `animate` | `boolean` | `true` | Draw on when the text scrolls into view. `false` shows the mark at once. |
| `delay` | `number` | `0` | Delay before drawing, in ms (added to the group's stagger). |
| `duration` | `number` | `700` | Drawing time in ms. |

Also accepts every `span` prop.

### MarkerGroup

Draws the `Marker`s inside it one after another, in document order, once the group scrolls into
view (or is wholly visible at the end of a page). Use it so a sentence with several marks reads
like someone annotating it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"div" \| "p" \| "span" \| "h1" \| "h2" \| "h3" \| "h4" \| "blockquote" \| "section"` | `"div"` | Element to render: usually the paragraph or heading that holds the markers. |
| `stagger` | `number` | `350` | Time between one marker starting and the next, in ms. Markers draw in document order. |

Also accepts every `div` prop.



---

# Marquee

> Endlessly scrolling row or column for client names, skills or testimonials, with edge fades, reverse direction, pause on hover or on demand and an optional scroll-velocity drive.

Category: Effects · Registry item: `@portfolio-kit/marquee` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/marquee) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/marquee.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/marquee
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/marquee.tsx` and the kit items it uses: `use-composed-refs`, `use-isomorphic-layout-effect`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  Marquee,
  MarqueePauseButton,
  MarqueeSeparator,
} from "@/components/portfolio/marquee"

<div>
  <Marquee label="Clients" duration={30} paused={false} pauseOnHover fade>
    <span>Halcyon Labs</span>
    <MarqueeSeparator />
    <span>Northwind Rail</span>
    <MarqueeSeparator />
    <span>Fieldnote</span>
    <MarqueeSeparator />
  </Marquee>
  <MarqueePauseButton paused={false} pauseLabel="Pause clients" />
</div>
```

## Examples

### Demo

A slow, edge-faded row of client names that pauses on hover.

```tsx
import { Marquee, MarqueeSeparator } from "@/components/portfolio/marquee"
import { typography } from "@/lib/typography"

const clients = ["Halcyon", "Tidewater", "Fieldnote", "Orbit", "Kiln", "Northpeak"]

export default function MarqueeDemo() {
  return (
    <div className="mx-auto flex max-w-5xl flex-col items-center gap-6 py-8">
      <p className={typography.eyebrow}>Trusted by teams at</p>
      <Marquee label="Clients" duration={30} gap="2.5rem" pauseOnHover className="w-full">
        {clients.map((client) => (
          <span key={client} className="flex items-center gap-10 font-heading text-3xl text-muted-foreground md:text-5xl">
            {client}
            <MarqueeSeparator className="text-xl" />
          </span>
        ))}
      </Marquee>
    </div>
  )
}
```

### Headline

An edge-to-edge band of display type between two rules, used as a divider between sections.

```tsx
import { Marquee, MarqueeSeparator } from "@/components/portfolio/marquee"

const phrases = ["Available for freelance", "Design engineering", "Based in Lisbon"]

export default function MarqueeHeadline() {
  return (
    <div className="border-y py-6 md:py-8">
      <Marquee label="Available for freelance design engineering, based in Lisbon" duration={28} gap="3rem" fade={false}>
        {phrases.map((phrase) => (
          <span key={phrase} className="flex items-center gap-12 font-heading text-5xl leading-none md:text-7xl">
            {phrase}
            <MarqueeSeparator className="text-[0.6em]" />
          </span>
        ))}
      </Marquee>
    </div>
  )
}
```

### Opposing rows

Two rows of skills running in opposite directions with `reverse`.

```tsx
import { cn } from "@/lib/utils"
import { Marquee } from "@/components/portfolio/marquee"

const design = ["Product design", "Design systems", "Prototyping", "Motion", "Accessibility", "Research"]
const code = ["React", "TypeScript", "CSS", "Next.js", "WebGL", "Testing"]

const chip = "inline-flex h-10 items-center rounded-pill border px-4 text-sm font-medium whitespace-nowrap"

export default function MarqueeRows() {
  return (
    <div className="mx-auto flex max-w-5xl flex-col gap-3 py-8">
      <Marquee label="Design skills" duration={36} gap="0.75rem" pauseOnHover>
        {design.map((skill) => (
          <span key={skill} className={cn(chip, "bg-background")}>
            {skill}
          </span>
        ))}
      </Marquee>
      <Marquee label="Engineering skills" duration={36} gap="0.75rem" reverse pauseOnHover>
        {code.map((skill) => (
          <span key={skill} className={cn(chip, "bg-muted font-mono text-xs")}>
            {skill}
          </span>
        ))}
      </Marquee>
    </div>
  )
}
```

### Vertical testimonials

Columns of testimonial cards moving in opposite directions with `orientation="vertical"`, and a `MarqueePauseButton` wired to `paused` so visitors can stop them to read. The second column appears on wider screens.

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"
import { Marquee, MarqueePauseButton } from "@/components/portfolio/marquee"
import {
  TestimonialAuthor,
  TestimonialCard,
  TestimonialQuote,
} from "@/components/portfolio/testimonial-card"

const testimonials = [
  {
    quote: "Our design system finally feels like one thing. Noa holds the whole product in their head.",
    name: "Ines Carvalho",
    role: "VP Product, Halcyon Labs",
  },
  {
    quote: "The prototype Noa built in week one became the product.",
    name: "Tomas Reyes",
    role: "Founder, Fieldnote",
  },
  {
    quote: "The most detail-oriented engineer I've worked with. Every interaction just feels right.",
    name: "Priya Anand",
    role: "Design Director, Orbit",
  },
  {
    quote: "A messy brief became a clear, beautiful site — and our team learned a lot along the way.",
    name: "Sam Okafor",
    role: "Owner, Kiln Ceramics",
  },
]

function Column({
  items,
  reverse,
  paused,
  className,
}: {
  items: typeof testimonials
  reverse?: boolean
  paused: boolean
  className?: string
}) {
  return (
    <Marquee
      orientation="vertical"
      duration={32}
      gap="1rem"
      reverse={reverse}
      paused={paused}
      pauseOnHover
      // Room for offset shadows (Brutalist) that the marquee's overflow would clip.
      className={cn("pr-1", className)}
    >
      {items.map((t) => (
        <TestimonialCard key={t.name}>
          <TestimonialQuote>{t.quote}</TestimonialQuote>
          <TestimonialAuthor name={t.name} position={t.role} />
        </TestimonialCard>
      ))}
    </Marquee>
  )
}

export default function MarqueeVertical() {
  const [paused, setPaused] = React.useState(false)
  return (
    <section aria-label="Testimonials" className="mx-auto flex max-w-3xl flex-col items-center gap-4">
      <div className="grid h-[32rem] w-full gap-4 sm:grid-cols-2">
        <Column items={testimonials} paused={paused} />
        <Column items={[...testimonials].reverse()} reverse paused={paused} className="hidden sm:flex" />
      </div>
      <MarqueePauseButton paused={paused} onPausedChange={setPaused} pauseLabel="Pause testimonials" />
    </section>
  )
}
```

### Scroll Velocity

Headline bands driven by the page: they rush while you scroll, run backwards after you scroll up, and lean into the motion. Scroll the preview.

```tsx
import { Marquee, MarqueeSeparator } from "@/components/portfolio/marquee"
import { typography } from "@/lib/typography"

const services = ["Brand identity", "Design systems", "Motion", "Web design", "Art direction"]

function Band({ muted = false }: { muted?: boolean }) {
  return services.map((service) => (
    <span
      key={service}
      className={`flex items-center gap-10 font-heading text-5xl whitespace-nowrap md:text-7xl ${muted ? "text-muted-foreground" : ""}`}
    >
      {service}
      <MarqueeSeparator className="text-[0.5em]" />
    </span>
  ))
}

export default function MarqueeScrollVelocity() {
  return (
    // A tall page with the bands pinned in view, so there's plenty to scroll while watching them.
    <div className="h-[300vh]">
      <div className="sticky top-0 flex h-dvh flex-col justify-center gap-8 overflow-x-clip">
        <p className={`${typography.eyebrow} px-6 text-center`}>Scroll up and down</p>
        <Marquee scrollVelocity={1} duration={30} gap="2.5rem" fade={false} label="Services">
          <Band />
        </Marquee>
        <Marquee scrollVelocity={1} reverse duration={36} gap="2.5rem" fade={false} aria-hidden>
          <Band muted />
        </Marquee>
      </div>
    </div>
  )
}
```

## API Reference

### Marquee

An infinite loop of its children: they're rendered `repeat` times and each
copy slides by exactly its own size plus `gap`, so the seam is invisible.
Pure CSS animation; JavaScript only drives `scrollVelocity` and keeps the copies out of the Tab order.
Under reduced motion and in print it shows its content once and still: rows wrap and center,
columns scroll (print: grow). Add a `MarqueePauseButton` so visitors can stop it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Scroll direction axis. Vertical marquees need a fixed height on the root. |
| `fade` | `boolean` | `true` | Fade the leading and trailing edges into the background. |
| `duration` | `number` | — | Seconds for one copy to travel its own length (default 40). Lower is faster. Sets the `--marquee-duration` CSS variable; leave it out to set the variable from CSS instead, e.g. `className="[--marquee-duration:20s] md:[--marquee-duration:40s]"`. |
| `gap` | `string` | — | Gap between items, any CSS length (default `2rem`). Sets `--marquee-gap`; leave it out to set the variable from CSS. |
| `reverse` | `boolean` | `false` | Scroll toward the end instead of the start. On right-to-left pages the default direction is mirrored too. |
| `pauseOnHover` | `boolean` | `false` | Pause while the pointer is over the marquee. It always pauses while something inside has keyboard focus. |
| `paused` | `boolean` | `false` | Stop the loop where it is. A loop that runs longer than five seconds next to other content needs a control to pause it (WCAG 2.2.2): keep this in state and toggle it with `MarqueePauseButton` (or your own button). |
| `repeat` | `number` | `3` | How many copies of the content to render (min 2). Increase for short content on wide screens so the loop never shows a gap. |
| `label` | `string` | — | Accessible name, e.g. "Clients". Makes the marquee a named group (not a landmark). Assistive tech and the keyboard meet the content once: the duplicate copies are hidden from them, though any visible copy can be clicked. |
| `scrollVelocity` | `number` | `0` | Drive the loop with page scroll: it speeds up while you scroll, runs backwards after you scroll up, eases back to its base speed when you stop, and the band leans slightly with the motion. The number scales the response (`1` is a good start, `0` turns it off). Still under reduced motion. |

Also accepts every `div` prop.

### MarqueeSeparator

Decorative mark between marquee items, hidden from assistive tech and tinted with the highlight.
Renders a dot sized to its font size (`text-[0.5em]` makes it half as big); pass children for a glyph such as `/`.

Also accepts every `span` prop.

### MarqueePauseButton

Pause/play toggle for a `Marquee` (WCAG 2.2.2), placed wherever it fits: below the row, beside it or
in a bar. A bordered icon button by default; hidden under reduced motion and in print, when nothing moves.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `paused` (required) | `boolean` | — | Whether the marquee it controls is paused (pass the same value to `Marquee`'s `paused`). |
| `onPausedChange` | `(paused: boolean) => void` | — | Called with the new value when the button is pressed. |
| `pauseLabel` | `string` | `"Pause"` | Accessible name, e.g. "Pause logos". The button is a toggle: pressed while paused. |

Also accepts every `button` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)



---

# Media Appearances

> Podcast episodes, video interviews and livestreams you appeared on, with show artwork, date, duration and listen/watch links per platform, as rows or cards.

Category: Content · Registry item: `@portfolio-kit/media-appearances` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/media-appearances) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/media-appearances.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/media-appearances
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/media-appearances.tsx` and the kit items it uses: `brand-icons`, `format`, `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  MediaAppearance,
  MediaAppearances,
} from "@/components/portfolio/media-appearances"

<MediaAppearances>
  <MediaAppearance
    type="podcast"
    show="The Handoff"
    heading="Design engineers and the space between"
    date="2026-02-11"
    duration="58:12"
    href="https://example.com/handoff/142"
  />
</MediaAppearances>
```

## Examples

### Demo

Podcasts, interviews and streams you've been on: show art, episode, date and duration, with a link per platform.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { MediaAppearance, MediaAppearances } from "@/components/portfolio/media-appearances"

export default function MediaAppearancesDemo() {
  return (
    <MediaAppearances className="mx-auto max-w-3xl">
      <MediaAppearance
        type="podcast"
        show="The Handoff"
        episode="Ep. 142"
        heading="Design engineers and the space between"
        date="2026-02-11"
        duration="58:12"
        artwork={<GenerativeArt seed="the-handoff" variant="bauhaus" />}
        href="https://example.com/handoff/142"
        links={[
          "https://open.spotify.com/episode/handoff-142",
          "https://podcasts.apple.com/podcast/the-handoff/142",
          "https://www.youtube.com/watch?v=handoff142",
        ]}
      />
      <MediaAppearance
        type="video"
        typeLabel="Interview"
        show="Frames Per Second"
        heading="How a motion system ships across four platforms"
        date="2025-11-20"
        duration="24:05"
        artwork={<GenerativeArt seed="frames-per-second" variant="portrait" />}
        href="https://example.com/fps/motion-system"
        links={["https://www.youtube.com/watch?v=fps-motion"]}
      />
      <MediaAppearance
        type="livestream"
        show="Friday Refactor"
        episode="Stream #88"
        heading="Rebuilding a portfolio live, from tokens to deploy"
        date="2025-09-05"
        duration="1:42:30"
        artwork={<GenerativeArt seed="friday-refactor" variant="interface" />}
        links={["https://www.twitch.tv/videos/friday-refactor-88", "https://www.youtube.com/watch?v=refactor88"]}
      />
      <MediaAppearance
        type="radio"
        show="Night Shift FM"
        heading="On quiet software"
        date="2025-04-17"
        duration={32}
        artwork={<GenerativeArt seed="night-shift" variant="orb" />}
        links={["https://soundcloud.com/night-shift-fm/quiet-software"]}
      />
    </MediaAppearances>
  )
}
```

### Cards

An artwork-led grid for a “Listen & watch” page. Podcast covers sit on a blurred backdrop; videos get a play glyph and a running time.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { MediaAppearance, MediaAppearances } from "@/components/portfolio/media-appearances"

export default function MediaAppearancesCards() {
  return (
    <MediaAppearances variant="cards" className="mx-auto max-w-5xl">
      <MediaAppearance
        type="podcast"
        show="The Handoff"
        episode="Ep. 142"
        heading="Design engineers and the space between"
        date="2026-02-11"
        duration="58:12"
        artwork={<GenerativeArt seed="the-handoff" variant="bauhaus" />}
        href="https://example.com/handoff/142"
        links={["https://open.spotify.com/episode/handoff-142", "https://podcasts.apple.com/podcast/the-handoff/142"]}
      />
      <MediaAppearance
        type="video"
        typeLabel="Interview"
        show="Frames Per Second"
        heading="How a motion system ships across four platforms"
        date="2025-11-20"
        duration="24:05"
        artwork={<GenerativeArt seed="frames-per-second" variant="portrait" />}
        href="https://example.com/fps/motion-system"
        links={["https://www.youtube.com/watch?v=fps-motion"]}
      />
      <MediaAppearance
        type="podcast"
        show="Small Batch Software"
        episode="Ep. 31"
        heading="Pricing a one-person product"
        date="2025-06-02"
        duration="46:40"
        artwork={<GenerativeArt seed="small-batch" variant="rings" />}
        href="https://example.com/small-batch/31"
        links={["https://open.spotify.com/episode/small-batch-31", "https://example.com/small-batch/feed.xml"]}
      />
    </MediaAppearances>
  )
}
```

### In a Section

A “Listen & watch” section with a one-line summary under each episode. Pass `children` for show notes or guests.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { MediaAppearance, MediaAppearances } from "@/components/portfolio/media-appearances"
import {
  Section,
  SectionContent,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

export default function MediaAppearancesInASection() {
  return (
    <Section id="media" size="sm">
      <SectionHeader>
        <SectionEyebrow index={6}>Media</SectionEyebrow>
        <SectionTitle>Listen &amp; watch</SectionTitle>
        <SectionDescription>Conversations about motion, design systems and working in small teams.</SectionDescription>
      </SectionHeader>
      <SectionContent>
        <MediaAppearances>
          <MediaAppearance
            show="The Handoff"
            episode="Ep. 142"
            heading="Design engineers and the space between"
            date="2026-02-11"
            duration="58:12"
            artwork={<GenerativeArt seed="the-handoff" variant="bauhaus" />}
            href="https://example.com/handoff/142"
            links={["https://open.spotify.com/episode/handoff-142", "https://podcasts.apple.com/podcast/the-handoff/142"]}
          >
            <p className="mt-1 max-w-xl text-sm leading-relaxed text-pretty text-muted-foreground">
              Why the best interfaces are negotiated in code, and how to hire for the role.
            </p>
          </MediaAppearance>
          <MediaAppearance
            type="video"
            show="Frames Per Second"
            heading="How a motion system ships across four platforms"
            date="2025-11-20"
            duration="24:05"
            artwork={<GenerativeArt seed="frames-per-second" variant="portrait" />}
            href="https://example.com/fps/motion-system"
            links={["https://www.youtube.com/watch?v=fps-motion"]}
          >
            <p className="mt-1 max-w-xl text-sm leading-relaxed text-pretty text-muted-foreground">
              A walkthrough of one easing curve, three durations and the tokens that keep them in sync.
            </p>
          </MediaAppearance>
        </MediaAppearances>
      </SectionContent>
    </Section>
  )
}
```

## API Reference

### MediaAppearances

The `<ul>` of `MediaAppearance`s, labelled "Media appearances" (override with `aria-label`).
`rows` for a compact ruled list, `cards` for an artwork-led grid. Nothing is embedded or plays
here: items link out to the episode page and platforms, so there's no autoplay to pause.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"rows" \| "cards"` | `"rows"` | `rows`: divided rows with small artwork, for a long list. `cards`: a grid of large artwork, for a few highlights. |

Also accepts every `ul` prop.

### MediaAppearance

One appearance. Extra `children` render under the meta line (a short summary, guests).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `show` (required) | `React.ReactNode` | — | Show, channel or station, e.g. "The Handoff". |
| `heading` | `React.ReactNode` | — | Episode or video title (the item's heading). Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `type` | `"podcast" \| "video" \| "livestream" \| "radio"` | `"podcast"` | Sets the icon and label, and how `cards` frame the artwork: square covers for `podcast`/`radio`, 16:9 with a play glyph for `video`/`livestream`. |
| `typeLabel` | `React.ReactNode` | — | Override the type label, e.g. "Interview" or "Panel". |
| `episode` | `React.ReactNode` | — | Episode number or label, e.g. `"Ep. 142"`. |
| `date` | `Date \| string` | — | ISO date (`"2025-06-12"`) or `Date`; rendered in a `<time>` ("Feb 11, 2026"). |
| `locale` | `string` | `"en-US"` | Locale for the date. |
| `duration` | `number \| string` | — | Minutes (`58`) or a clock string (`"1:12:30"`). Shown as "1 hr 12 min" in a `<time>` with an ISO duration (`PT1H12M30S`). |
| `artwork` | `React.ReactNode` | — | Cover art: image URL or node (e.g. `<GenerativeArt />`). Omit for a neutral placeholder with the type icon. |
| `href` | `string` | — | Main link (the episode page). The whole row or card becomes clickable. External URLs open in a new tab and show ↗. |
| `links` | `LinkInput[]` | `[]` | Platform links, rendered as icon buttons after the item. Pass URLs and the platform is detected (Spotify, YouTube, SoundCloud, Twitch, Vimeo, Apple Podcasts, RSS), or `{ href, label }` to name one yourself. |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the title. Use `h4` when the list sits under an `h3`. |
| `labels` | `Partial<MediaAppearanceLabels>` | — | Wording, for translations: `{ listen: "Anhören auf", watch: "Ansehen auf", platforms: "Plattformen", hr: "Std.", min: "Min.", spokenDuration: (h, m) => … }`. Durations show the short units and are read with `spokenDuration`. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text after external links. |

Also accepts every `li` prop.

### type LinkInput

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `href` (required) | `string` | — |  |
| `label` | `string` | — |  |

### type MediaAppearanceLabels

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `listen` (required) | `string` | — | Before platform names for `podcast`/`radio`: "Listen on Spotify". |
| `watch` (required) | `string` | — | Before platform names for `video`/`livestream`: "Watch on YouTube". |
| `platforms` (required) | `string` | — | Accessible name of each item's list of platform links. |
| `hr` (required) | `string` | — | Short unit after the hours: "1 hr". |
| `min` (required) | `string` | — | Short unit after the minutes: "12 min". |
| `spokenDuration` (required) | `(hours: number, minutes: number) => string` | — | The duration as read by screen readers: "1 hour 12 minutes". `minutes` is the rest after the hours. |

## Used in templates

- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)



---

# Media

> Aspect-ratio frame for images, video or artwork, with blur-up loading, optional hover zoom and an optional caption.

Category: Utilities · Registry item: `@portfolio-kit/media` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/media) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/media.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/media
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/media.tsx` and the kit items it uses: `typography`, `use-composed-refs`, `use-in-view`, `use-page-visible`, `use-reduced-motion`, `use-save-data`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { Media, mediaVariants } from "@/components/portfolio/media"
```

## Examples

### Demo

A captioned figure with a fixed aspect ratio and a slow hover zoom — for case-study images, video or artwork.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Media } from "@/components/portfolio/media"

export default function MediaDemo() {
  return (
    <Media
      ratio="video"
      radius="lg"
      zoom
      bordered
      caption="Fig. 1 — Field survey at dawn, Sagres. The buoy array sits just past the second ridge."
      className="w-lg max-w-full"
    >
      {/* Swap in your photo: <Media src="/work/sagres.jpg" alt="…" /> fades in from a blur once loaded.
          Above the fold, add `priority`; for responsive files pass imgProps={{ srcSet, sizes }}. */}
      <GenerativeArt seed="sagres-dawn" variant="landscape" label="Hills fading into haze under a low morning sun" />
    </Media>
  )
}
```

### Ratios

Named aspect ratios keep a grid aligned before anything loads — square, portrait, photo, video, wide and more.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Media } from "@/components/portfolio/media"

const frames = [
  { ratio: "square", art: "portrait" },
  { ratio: "portrait", art: "landscape" },
  { ratio: "photo", art: "interface" },
  { ratio: "video", art: "landscape" },
] as const

export default function MediaRatios() {
  return (
    <div className="mx-auto grid max-w-4xl grid-cols-2 items-start gap-4 md:grid-cols-4">
      {frames.map((frame) => (
        <Media key={frame.ratio} ratio={frame.ratio} bordered caption={frame.ratio}>
          <GenerativeArt seed={`ratio-${frame.ratio}`} variant={frame.art} />
        </Media>
      ))}
    </div>
  )
}
```

### Case Study Grid

A wide lead image over two portraits — the classic case-study spread, with captions in mono.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Media } from "@/components/portfolio/media"

export default function MediaCaseStudyGrid() {
  return (
    <div className="mx-auto grid max-w-4xl gap-4 sm:grid-cols-2 md:gap-6">
      <Media
        ratio="wide"
        radius="lg"
        bordered
        caption="01 — Dashboard overview at 1440px"
        className="sm:col-span-2"
      >
        <GenerativeArt seed="tidewater-overview" variant="interface" />
      </Media>
      <Media ratio="portrait" radius="lg" bordered caption="02 — Turbine detail, mobile">
        <GenerativeArt seed="tidewater-detail" variant="interface" />
      </Media>
      <Media ratio="portrait" radius="lg" bordered caption="03 — Alert states">
        <GenerativeArt seed="tidewater-alerts" variant="interface" />
      </Media>
    </div>
  )
}
```

### Linked Tile

Inside a `group` link, `zoom` reacts to hovering the whole tile — not just the image.

```tsx
import { ArrowUpRight } from "lucide-react"

import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Media } from "@/components/portfolio/media"
import { typography } from "@/lib/typography"

export default function MediaLinked() {
  return (
    <a
      href="#fieldnote"
      className="group flex w-sm max-w-full flex-col gap-4 rounded-2xl outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
    >
      <Media ratio="portrait" radius="lg" zoom>
        <GenerativeArt seed="fieldnote" variant="interface" />
      </Media>
      <span className="flex items-start justify-between gap-4">
        <span className="flex flex-col gap-1">
          <span className={typography.heading}>Fieldnote</span>
          <span className={typography.body}>Identity and marketing site, 2024</span>
        </span>
        <ArrowUpRight
          aria-hidden
          className="mt-1 size-4 shrink-0 text-muted-foreground transition-[translate,color] duration-300 ease-smooth group-hover:-translate-y-0.5 group-hover:translate-x-0.5 group-hover:text-foreground motion-reduce:transition-none"
        />
      </span>
    </a>
  )
}
```

## API Reference

### Media

A fixed-ratio frame. Pass `src` for an image, `video` for a looping clip, or `children` for
artwork and overlays (they can be combined — children sit on top).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | `"photo" \| "video" \| "square" \| "portrait" \| "wide" \| "tall" \| "auto"` | `"photo"` | Aspect ratio of the frame: `photo` 4:3, `video` 16:9, `square`, `portrait` 4:5, `tall` 3:4, `wide` 21:9. `auto` sets no ratio: the image or video keeps its own shape (pass `width`/`height` in `imgProps` or `videoProps` to reserve the space before it loads), or size the frame yourself with `className`/`frameClassName` (`aspect-*`, `size-full`). Artwork alone has no size of its own. |
| `radius` | `"default" \| "none" \| "lg" \| "full"` | `"default"` | Corner radius: `default` follows the theme, `lg` is larger, `full` makes a circle (use with `square`), `none` is square. |
| `bordered` | `boolean` | `false` | Draw a hairline border, for screenshots with white edges on a white page. |
| `src` | `string` | — | Image URL. Loads lazily and fades in from a blur once decoded (at once under reduced motion). |
| `alt` | `string` | `""` | Text alternative for the image or video. Describe what the media shows when it carries content; leave it empty (the default) when it's decorative or the caption or nearby text already says it. |
| `priority` | `boolean` | `false` | Mark the image as the page's main, above-the-fold image (the LCP element): it loads eagerly with high fetch priority and shows at once, without the blur-up fade. |
| `video` | `string` | — | Video source. Plays muted and looped while on screen and the tab is visible. Under reduced motion, reduced data or Save-Data it doesn't start; it shows `poster` and controls instead. |
| `poster` | `string` | — | Poster frame shown before the video plays (and instead of it under reduced motion or data saving). |
| `zoom` | `boolean` | `false` | Scale the media when the frame (or any ancestor `.group`) is hovered. Off for reduced motion. |
| `caption` | `React.ReactNode` | — | Caption under the frame. When set, Media renders a `<figure>` with a `<figcaption>`; otherwise a single `<div>`. |
| `frameClassName` | `string` | — | Classes for the frame itself. With a `caption`, `className` styles the outer `<figure>`, so use this for a per-breakpoint ratio: `ratio="auto" frameClassName="aspect-[4/5] sm:aspect-video"`. |
| `children` | `React.ReactNode` | — | Artwork (e.g. `<GenerativeArt />`) or overlays rendered inside the frame, on top of any image or video. |
| `imgProps` | `Omit<React.ComponentProps<"img">, "src" \| "alt">` | — | Extra props for the `<img>`: `sizes` and `srcSet` for responsive images, `width`/`height`… |
| `videoProps` | `Omit<React.ComponentProps<"video">, "src" \| "poster">` | — | Extra props for the `<video>` (`controls`, `preload`, tracks…). With `controls`, the visitor's play and pause win. |

Also accepts every `figure` prop.

## Used in templates

- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Newsletter Form

> Email sign-up form with inline validation and loading, success and error states. Pill-shaped inline field, stacked form or titled card.

Category: Content · Registry item: `@portfolio-kit/newsletter-form` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/newsletter-form) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/newsletter-form.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/newsletter-form
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/newsletter-form.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

shadcn/ui primitives: `button`, `input`.

## Usage

```tsx
import { NewsletterForm, newsletterFormVariants } from "@/components/portfolio/newsletter-form"
```

## Examples

### Demo

A pill-shaped email field with the button inside. Validation, loading and success states are built in; you only supply `onSubscribe`.

```tsx
import { NewsletterForm } from "@/components/portfolio/newsletter-form"

// Replace the demo delay with your API request. Send JSON with Content-Type: application/json,
// check response.ok, and throw on failure so the form shows its error state. No API route? Drop
// `onSubscribe` and pass your provider's form endpoint as `action` with `method="post"`.
const subscribe = () => new Promise<void>((resolve) => setTimeout(resolve, 800))

export default function NewsletterFormDemo() {
  return <NewsletterForm onSubscribe={subscribe} note="Join 2,400 readers. One email a month, no spam." className="w-full" />
}
```

### Card

A card with a heading and a short pitch, for the end of an article or a newsletter page.

```tsx
import { NewsletterForm } from "@/components/portfolio/newsletter-form"

const subscribe = () => new Promise<void>((resolve) => setTimeout(resolve, 800))

export default function NewsletterFormCard() {
  return (
    <NewsletterForm
      variant="card"
      heading="Notes from the workbench"
      description="Essays on design systems, motion and front-end craft — plus the occasional sketch. Straight to your inbox."
      note="Join 2,400 readers. Unsubscribe anytime."
      onSubscribe={subscribe}
    />
  )
}
```

### Error Handling

The stacked layout with a visible label, plus server errors: throw from `onSubscribe` and the message is shown and announced inline. Submit an address starting with “taken” to see it.

```tsx
import { NewsletterForm } from "@/components/portfolio/newsletter-form"
import { typography } from "@/lib/typography"

async function subscribe(email: string) {
  await new Promise((resolve) => setTimeout(resolve, 800))
  // Whatever you throw becomes the inline message.
  if (email.startsWith("taken")) throw new Error("That address is already on the list.")
}

export default function NewsletterFormErrorHandling() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-5">
      <div className="flex flex-col gap-2">
        <h3 className={typography.heading}>Enjoyed this essay?</h3>
        <p className={typography.body}>Get the next one by email — roughly once a month.</p>
      </div>
      <NewsletterForm
        variant="stacked"
        showLabel
        buttonLabel="Get the newsletter"
        successMessage="Thanks! Check your inbox to confirm."
        onSubscribe={subscribe}
      />
    </div>
  )
}
```

### In a Section

A full-width sign-up band above the footer: text on the left, form on the right, stacked on phones.

```tsx
import { NewsletterForm } from "@/components/portfolio/newsletter-form"
import { Section } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

const subscribe = () => new Promise<void>((resolve) => setTimeout(resolve, 800))

export default function NewsletterFormInASection() {
  return (
    <Section tone="muted" spacing="sm" divider>
      <div className="flex flex-col gap-6 md:flex-row md:items-center md:justify-between md:gap-12">
        <div className="flex max-w-md flex-col gap-2">
          <h2 className="font-heading text-2xl leading-tight md:text-3xl">Get new essays by email</h2>
          <p className={typography.body}>A short letter when something new ships. Unsubscribe anytime.</p>
        </div>
        <NewsletterForm onSubscribe={subscribe} note="No spam. One email a month, at most." className="md:w-md" />
      </div>
    </Section>
  )
}
```

## API Reference

### NewsletterForm

An email sign-up form that handles its own states. The address is checked on submit (and when
you leave a filled-in field): an invalid one shows an inline message linked to the field, which
gets focus and stays marked until the address is valid. While `onSubscribe` runs the button
shows a spinner, repeat submits are ignored and screen readers hear `loadingLabel`. On success
the message replaces the field and takes focus; a failure shows the error under the field, moves
focus back to it and the visitor can retry.

Without `onSubscribe` (and before JavaScript loads) it is a plain HTML form: pass your email
provider's endpoint as `action` with `method="post"`. The field is named `email`, and the browser
checks it before sending. A sign-up can't be used on paper, so the form hides itself in print.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"inline" \| "stacked" \| "card"` | `"inline"` | `inline`: field and button in one pill, for footers and heroes. `stacked`: field above a full-width button. `card`: adds a heading and description in a card. |
| `onSubscribe` | `(email: string) => Promise<void> \| void` | — | Called with a valid, trimmed email. Resolve on success; throw (or reject) on failure. The error's `message` is shown inline, e.g. `throw new Error("Already subscribed.")`. Without it, the browser submits the form to `action` (see the component description). |
| `placeholder` | `string` | `"you@example.com"` | Example address shown in the empty field. |
| `buttonLabel` | `string` | `"Subscribe"` | Submit button text. |
| `loadingLabel` | `string` | `"Subscribing…"` | Announced to screen readers while `onSubscribe` runs (the button shows a spinner). |
| `note` | `React.ReactNode` | — | Small print under the field, e.g. "Join 2,400 readers. No spam." Replaced by status messages while they show. |
| `heading` | `React.ReactNode` | — | `card` variant heading. |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Level of the `card` heading, to fit the page outline. |
| `description` | `React.ReactNode` | — | `card` variant description under the heading. |
| `label` | `string` | `"Email address"` | Field label (the input's accessible name). Visually hidden unless `showLabel` is set. |
| `showLabel` | `boolean` | `false` | Show `label` above the field instead of hiding it visually. |
| `successMessage` | `React.ReactNode` | `"You're in! Check your inbox to confirm."` | Replaces the field after `onSubscribe` resolves; focus moves to it and screen readers read it. |
| `errorMessage` | `React.ReactNode` | `"Something went wrong. Please try again."` | Fallback error text when `onSubscribe` rejects without a message. |
| `invalidMessage` | `React.ReactNode` | `"Please enter a valid email address."` | Shown when the address fails validation (on submit, or on leaving a filled-in field). |
| `onStatusChange` | `(status: "idle" \| "loading" \| "success" \| "error") => void` | — | Fired with the new status after every transition. |

Also accepts every `form` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Links](https://www.parthjadhav.com/products/portfolio-kit/templates/links.md)
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Next Project

> End-of-case-study pager: a large “next project” link whose cover widens on hover, as a full-width hero or a previous/next split.

Category: Work · Registry item: `@portfolio-kit/next-project` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/next-project) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/next-project.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/next-project
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/next-project.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  NextProject,
  NextProjectLink,
} from "@/components/portfolio/next-project"

<NextProject>
  <NextProjectLink direction="previous" href="/work/lumen" heading="Lumen" meta="Halcyon Labs" />
  <NextProjectLink
    href="/work/fieldnote"
    heading="Fieldnote"
    meta="03 / 06"
    media={<img src="/fieldnote.jpg" alt="" />}
  />
</NextProject>
```

## Examples

### Demo

End a case study with a large link to the next one. Its cover widens on hover, with a compact “previous” row above.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { NextProject, NextProjectLink } from "@/components/portfolio/next-project"
import { Container } from "@/components/portfolio/section"

export default function NextProjectDemo() {
  return (
    <Container className="py-12 md:py-16">
      <NextProject>
        <NextProjectLink direction="previous" href="#lumen" heading="Lumen" meta="Halcyon Labs" />
        <NextProjectLink
          href="#fieldnote"
          heading="Fieldnote"
          meta="03 / 06"
          media={<GenerativeArt seed="fieldnote" variant="bauhaus" />}
        />
      </NextProject>
    </Container>
  )
}
```

### Split

Previous and next side by side, each with a cover, for portfolios that are browsed in both directions.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { NextProject, NextProjectLink } from "@/components/portfolio/next-project"
import { Container } from "@/components/portfolio/section"

export default function NextProjectSplit() {
  return (
    <Container className="py-12 md:py-16">
      <NextProject variant="split">
        <NextProjectLink
          direction="previous"
          href="#lumen"
          heading="Lumen"
          meta="2025"
          media={<GenerativeArt seed="lumen" variant="interface" hue={250} />}
        />
        <NextProjectLink
          href="#fieldnote"
          heading="Fieldnote"
          meta="2024"
          media={<GenerativeArt seed="fieldnote" variant="bauhaus" />}
        />
      </NextProject>
    </Container>
  )
}
```

### Text Only

Drop the covers for a typographic pager that suits writing-led and minimal portfolios.

```tsx
import { NextProject, NextProjectLink } from "@/components/portfolio/next-project"
import { Container } from "@/components/portfolio/section"

export default function NextProjectTextOnly() {
  return (
    <Container className="py-12 md:py-16">
      <NextProject variant="split" aria-label="More case studies">
        <NextProjectLink direction="previous" href="#kiln" heading="Kiln" meta="Kiln Ceramics" />
        <NextProjectLink href="#paperplane" eyebrow="Up next" heading="Paperplane" meta="Open source" />
      </NextProject>
    </Container>
  )
}
```

## API Reference

### NextProject

A `<nav>` (labelled "More projects" by default) holding one or two `NextProjectLink`s.
`hero`: a full-width next link, with an optional compact "previous" row above it. `split`: previous and next side by side.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"hero" \| "split"` | `"hero"` | `hero`: one large "next project" link that closes the page. `split`: previous and next side by side. |

Also accepts every `nav` prop.

### NextProjectLink

One link per project. The whole block is the click target.
In the `hero` variant a `previous` link renders as a compact row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` (required) | `string` | — | The project page. |
| `heading` | `React.ReactNode` | — | Project name, set large. Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `direction` | `"next" \| "previous"` | `"next"` | `next` gets the big treatment; `previous` is a compact row in `hero` and the first half in `split`. |
| `eyebrow` | `React.ReactNode` | — | Label above the heading. Defaults to "Next project" / "Previous project". |
| `meta` | `React.ReactNode` | — | Small text on the eyebrow row, e.g. "03 / 06" or the client. |
| `media` | `React.ReactNode` | — | Cover image or artwork that peeks out and expands on hover. |

Also accepts every `a` prop.

## Used in templates

- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)



---

# Now Playing

> Music widget: album art, track and artist with an animated equalizer while playing, or “Last played” with a date or relative time. Card or one-line inline style.

Category: Content · Registry item: `@portfolio-kit/now-playing` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/now-playing) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/now-playing.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/now-playing
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/now-playing.tsx` and the kit items it uses: `brand-icons`, `format`, `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import { NowPlaying, nowPlayingVariants, Equalizer } from "@/components/portfolio/now-playing"
```

## Examples

### Demo

A small music card for an about page or bento grid: album art, track and artist, with an equalizer while something is playing.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { NowPlaying } from "@/components/portfolio/now-playing"

export default function NowPlayingDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <p className="font-mono text-xs tracking-[0.16em] text-muted-foreground uppercase">On the studio speakers</p>
      <NowPlaying
        playing
        track="Low Tide Lanterns"
        artist="The Quiet Harbour"
        album="Salt & Signal"
        cover={<GenerativeArt seed="salt-signal" variant="orb" />}
        href="https://example.com/tracks/low-tide-lanterns"
        className="max-w-none"
      />
    </div>
  )
}
```

### Last Played

When nothing is playing, show the most recent track and when it played. Any service from brand-icons works.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { NowPlaying } from "@/components/portfolio/now-playing"

export default function NowPlayingLastPlayed() {
  return (
    <NowPlaying
      track="Paper Satellites"
      artist="Mira Oduya"
      album="Night Shift Radio"
      cover={<GenerativeArt seed="night-shift" variant="rings" />}
      href="https://example.com/tracks/paper-satellites"
      service="soundcloud"
      playedAt="2026-03-01T21:40:00Z"
      // "11 hours ago" needs a reference time. Without `now` it reads "Mar 1, 2026", which stays
      // true on a static page and renders the same on the server and in the browser.
      now="2026-03-02T08:40:00Z"
    />
  )
}
```

### Inline

A single line for a footer, sidebar or bio. Long titles truncate (hover shows the full line); without `now`, the last play shows as a date.

```tsx
import { NowPlaying } from "@/components/portfolio/now-playing"

export default function NowPlayingInline() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <NowPlaying variant="inline" playing track="Low Tide Lanterns" artist="The Quiet Harbour" href="https://example.com/tracks/low-tide-lanterns" />
      <NowPlaying
        variant="inline"
        track="Paper Satellites (Extended Night Mix)"
        artist="Mira Oduya"
        href="#paper-satellites"
        playedAt="2026-03-01T21:40:00Z"
      />
    </div>
  )
}
```

### In a Footer

The inline style in a footer's small-print row, sized down to match the copyright line.

```tsx
import { NowPlaying } from "@/components/portfolio/now-playing"
import { SiteFooter, SiteFooterBottom, SiteFooterBrand } from "@/components/portfolio/site-footer"
import { typography } from "@/lib/typography"

export default function NowPlayingInAFooter() {
  return (
    <SiteFooter>
      <SiteFooterBrand>
        <p className="font-heading text-2xl">Noa Vale</p>
        <p className={typography.body}>Design engineer building calm, fast interfaces. Based in Lisbon.</p>
      </SiteFooterBrand>
      <SiteFooterBottom>
        <p>© 2026 Noa Vale</p>
        <NowPlaying
          variant="inline"
          playing
          track="Low Tide Lanterns"
          artist="The Quiet Harbour"
          href="#low-tide-lanterns"
          className="text-xs"
        />
      </SiteFooterBottom>
    </SiteFooter>
  )
}
```

## API Reference

### Equalizer

Four bars in the highlight color: the "playing" indicator, also usable on its own. They bounce
four times (under five seconds) and then rest; still under reduced motion and in print.
Decorative (`aria-hidden`): pair it with text such as "Now playing".

Also accepts every `span` prop.

### NowPlaying

What you're listening to. `card` shows album art, status, track and artist, and becomes one
link when `href` is set; `inline` is a single truncating line for footers and bios. Feed it from
your music service's API (e.g. Spotify's "currently playing" endpoint) on the server or client.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `track` (required) | `string` | — | Track title (the card's heading). Wraps to two lines in the `card`; the `inline` line truncates and shows the full text on hover. |
| `artist` (required) | `string` | — | Artist or band name, shown under the track. |
| `variant` | `"card" \| "inline"` | `"card"` | `card`: album art, track and artist in a small card. `inline`: one line of text for a footer, sidebar or bio. |
| `album` | `string` | — | Shown after the artist in the `card` variant. |
| `cover` | `React.ReactNode` | — | Album art: image URL or node (e.g. `<GenerativeArt />`). Omit for a neutral disc placeholder. The square frame is sized up front, so art never shifts the layout. |
| `href` | `string` | — | Link to the track. Makes the whole card (or line) clickable. External URLs open in a new tab and show ↗. |
| `playing` | `boolean` | `false` | Currently playing → equalizer + "Now playing"; otherwise "Last played" + when. |
| `playedAt` | `Date \| string` | — | When the track was last played (`Date` or ISO string). Shown as "11 hours ago" when `now` is set, otherwise as a date ("Mar 1, 2026"). |
| `now` | `Date \| string` | — | Reference time for a relative "Last played" ("11 hours ago"). Without it the date is shown instead: reading the clock here would differ between server and browser and go stale on static pages. |
| `service` | `BrandName` | `"spotify"` | Service icon from `brand-icons` (`spotify`, `soundcloud`, `youtube`…). |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the track in the `card` variant, to fit your page outline. |
| `locale` | `string` | `"en-US"` | Locale for the date or relative time. |
| `labels` | `Partial<NowPlayingLabels>` | — | Status text, for translations: `{ playing: "Läuft gerade", lastPlayed: "Zuletzt gehört" }`. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text after an external track link. |

Also accepts every `div` prop.

### type NowPlayingLabels

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `playing` (required) | `string` | — | Status while `playing`. |
| `lastPlayed` (required) | `string` | — | Status otherwise. |

## Used in templates

- [Links](https://www.parthjadhav.com/products/portfolio-kit/templates/links.md)
- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)



---

# Now

> A /now page block listing what you're building, reading and learning, with an “updated” date. Card grid or divided list.

Category: About · Registry item: `@portfolio-kit/now` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/now) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/now.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/now
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/now.tsx` and the kit items it uses: `format`, `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import { Now, NowItem } from "@/components/portfolio/now"

<Now updated="2025-10-14" meta="Lisbon, Portugal">
  <NowItem label="Building" href="/work/lumen">
    Lumen 2.0, a token pipeline for web, iOS and Android.
  </NowItem>
  <NowItem label="Reading">A slow re-read of a classic on typographic style.</NowItem>
  <NowItem label="Learning">Shader programming, one sketch every Sunday.</NowItem>
</Now>
```

## Examples

### Demo

What has your attention this season, with an “updated” date so visitors know how current it is.

```tsx
import { BookOpen, Hammer, Sprout } from "lucide-react"

import { Now, NowItem } from "@/components/portfolio/now"
import { Section } from "@/components/portfolio/section"

export default function NowDemo() {
  return (
    <Section spacing="sm">
      <Now
        updated="2025-10-14"
        meta="Lisbon, Portugal"
        description="A snapshot of what has my attention this season, inspired by the /now page movement."
      >
        <NowItem icon={<Hammer />} label="Building" href="#lumen">
          Lumen 2.0 — a token pipeline that ships themes to web, iOS and Android from one source.
        </NowItem>
        <NowItem icon={<BookOpen />} label="Reading">
          A slow re-read of a classic on typographic style, one chapter a week.
        </NowItem>
        <NowItem icon={<Sprout />} label="Learning" href="#sketches" linkLabel="See the sketches">
          Shader programming, badly. Small WebGL sketches every Sunday.
        </NowItem>
      </Now>
    </Section>
  )
}
```

### List

Divided rows with icons and labels in their own column. A calmer layout for a dedicated /now page.

```tsx
import { Dumbbell, Hammer, Headphones, Sprout } from "lucide-react"

import { Now, NowItem } from "@/components/portfolio/now"
import { Section } from "@/components/portfolio/section"

export default function NowList() {
  return (
    <Section spacing="sm" size="sm">
      <Now variant="list" heading="Now" as="h1" updated="2025-10-14" meta="Lisbon, Portugal">
        <NowItem icon={<Hammer />} label="Building" href="#lumen">
          Lumen 2.0 — a token pipeline that ships themes to web, iOS and Android from one source.
        </NowItem>
        <NowItem icon={<Sprout />} label="Learning">
          Shader programming, badly. Small WebGL sketches every Sunday.
        </NowItem>
        <NowItem icon={<Headphones />} label="Listening">
          Ambient records from the late seventies while I work.
        </NowItem>
        <NowItem icon={<Dumbbell />} label="Training">
          For a half marathon along the river in the spring.
        </NowItem>
      </Now>
    </Section>
  )
}
```

### Emoji

Emoji instead of icons for a more personal tone. Any node works as the icon.

```tsx
import { Now, NowItem } from "@/components/portfolio/now"
import { Section } from "@/components/portfolio/section"

export default function NowEmoji() {
  return (
    <Section spacing="sm">
      <Now
        heading="This season"
        updated="2025-09-30"
        description="Less screen time, more sketchbooks. Here's what I'm up to between projects."
      >
        <NowItem icon="🛠️" label="Making">
          A tiny type-specimen generator for my own fonts, one weight at a time.
        </NowItem>
        <NowItem icon="📷" label="Shooting" href="#film" linkLabel="Latest roll">
          Expired colour film on walks around the old town.
        </NowItem>
        <NowItem icon="🌱" label="Growing">
          Basil, chillies and a stubborn lemon tree on the studio balcony.
        </NowItem>
      </Now>
    </Section>
  )
}
```

## API Reference

### Now

The whole block: a header ("Updated …" stamp, heading, intro) and a list of `NowItem`s.
Renders a `<section>` labelled by its heading.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"grid" \| "list" \| null` | `"grid"` | `grid` shows each item as a card; `list` as divided rows with the label in its own column. |
| `heading` | `React.ReactNode` | — | The section heading. Defaults to "What I’m doing now"; pass `null` to render no visible heading (label the section with `aria-label` instead). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `as` | `"h1" \| "h2" \| "h3" \| "h4"` | `"h2"` | Heading level, so the block fits your page outline (`h1` on a dedicated /now page). |
| `description` | `React.ReactNode` | — | Short intro under the heading. |
| `updated` | `Date \| string` | — | When the page was last updated. Day strings like "2025-10-14" are read as that calendar day; shown as "Updated October 14, 2025" in a `<time>`. |
| `locale` | `string` | `"en-US"` | Locale for the updated date (default `en-US`, so the server and browser agree). |
| `updatedLabel` | `React.ReactNode` | `"Updated"` | Text before the date. Translate it together with `locale`, e.g. `"Aktualisiert"`. |
| `meta` | `React.ReactNode` | — | Extra meta after the date, e.g. a location. |
| `listClassName` | `string` | — | Class for the list that wraps the items. |
| `headerClassName` | `string` | — | Class for the header that holds the meta line, heading and description. |
| `titleClassName` | `string` | — | Class for the heading. |
| `descriptionClassName` | `string` | — | Class for the description. |
| `metaClassName` | `string` | — | Class for the "Updated …" meta line (e.g. `order-last` to move it under the description). |

Also accepts every `section` prop.

### NowItem

One thing you're doing now: a label, a sentence and an optional link.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `React.ReactNode` | — | Short verb, e.g. "Building", "Reading". |
| `children` (required) | `React.ReactNode` | — | What you're doing, in a sentence or two. |
| `icon` | `React.ReactNode` | — | A lucide icon or an emoji, shown in a small tile. |
| `href` | `string` | — | Optional link to more (the project, the book…). External links open in a new tab and say so to screen readers. |
| `linkLabel` | `React.ReactNode` | `"Take a look"` | Link text. A string `label` is added for screen readers ("Take a look (Building)"), so repeated link texts stay distinct. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added when `href` opens in a new tab. Translate it here. |
| `textClassName` | `string` | — | Class for the text block (the item's children). |

Also accepts every `li` prop.

## Used in templates

- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Number Ticker

> Counts up to a number when it scrolls into view — locale-aware formatting, compact notation, prefix/suffix and zero layout shift.

Category: Utilities · Registry item: `@portfolio-kit/number-ticker` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/number-ticker) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/number-ticker.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/number-ticker
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/number-ticker.tsx` and the kit items it uses: `use-composed-refs`, `use-in-view`, `use-isomorphic-layout-effect`, `use-reduced-motion`.

## Usage

```tsx
import { NumberTicker } from "@/components/portfolio/number-ticker"
```

## Examples

### Demo

A headline number that counts up once it scrolls into view. Width is reserved up front, so nothing around it shifts.

```tsx
import { NumberTicker } from "@/components/portfolio/number-ticker"
import { typography } from "@/lib/typography"

export default function NumberTickerDemo() {
  return (
    <div className="flex flex-col items-center gap-3 text-center">
      <NumberTicker value={1284} className="font-heading text-7xl leading-none md:text-8xl" />
      <p className={typography.eyebrow}>Commits shipped this year</p>
    </div>
  )
}
```

### Stats Row

A row of key numbers under an intro — prefixes, suffixes and compact notation keep each figure short.

```tsx
import { NumberTicker } from "@/components/portfolio/number-ticker"
import { typography } from "@/lib/typography"

const stats = [
  { label: "Years in practice", value: 9, suffix: "+" },
  { label: "Products shipped", value: 42 },
  { label: "Raised by clients", value: 18_400_000, prefix: "$", compact: true, decimals: 1 },
  { label: "Satisfaction", value: 98, suffix: "%" },
]

export default function NumberTickerStatsRow() {
  return (
    <dl className="mx-auto grid max-w-5xl grid-cols-2 gap-x-6 gap-y-10 border-t pt-8 md:grid-cols-4">
      {stats.map((stat, i) => (
        <div key={stat.label} className="flex flex-col gap-2">
          <dt className={typography.eyebrow}>{stat.label}</dt>
          <dd>
            <NumberTicker
              value={stat.value}
              prefix={stat.prefix}
              suffix={stat.suffix}
              compact={stat.compact}
              decimals={stat.decimals}
              delay={i * 120}
              className="font-heading text-4xl leading-none sm:text-5xl md:text-6xl"
            />
          </dd>
        </div>
      ))}
    </dl>
  )
}
```

### Formats

Pass `formatOptions` for currency, percent or units, `locale` for your site’s number format (default `en-US`), and `from` for a custom starting value.

```tsx
import { NumberTicker } from "@/components/portfolio/number-ticker"

export default function NumberTickerFormats() {
  const rows = [
    {
      label: "Currency",
      ticker: <NumberTicker value={12500} formatOptions={{ style: "currency", currency: "USD" }} />,
    },
    {
      label: "Percent",
      ticker: <NumberTicker value={0.873} decimals={1} formatOptions={{ style: "percent" }} />,
    },
    {
      label: "Unit",
      ticker: (
        <NumberTicker value={2140} formatOptions={{ style: "unit", unit: "kilometer" }} />
      ),
    },
    { label: "de-DE", ticker: <NumberTicker value={1234567.89} locale="de-DE" decimals={2} /> },
    { label: "From 1990", ticker: <NumberTicker value={2025} from={1990} formatOptions={{ useGrouping: false }} /> },
  ]

  return (
    <dl className="grid w-full max-w-sm grid-cols-[auto_1fr] items-baseline gap-x-8 gap-y-4">
      {rows.map((row) => (
        <div key={row.label} className="contents">
          <dt className="font-mono text-xs text-muted-foreground">{row.label}</dt>
          <dd className="text-right font-heading text-3xl">{row.ticker}</dd>
        </div>
      ))}
    </dl>
  )
}
```

### Inline in Copy

Tickers sit in running text like any other word — style them with a heavier color to make the numbers the point.

```tsx
import { NumberTicker } from "@/components/portfolio/number-ticker"

export default function NumberTickerInline() {
  return (
    <p className="w-full max-w-lg text-xl leading-snug text-pretty text-muted-foreground md:text-2xl">
      Since 2016 I&rsquo;ve shipped <NumberTicker value={60} className="font-medium text-foreground" /> projects for{" "}
      <NumberTicker value={34} className="font-medium text-foreground" /> clients and written{" "}
      <NumberTicker value={1.2} decimals={1} suffix="M" className="font-medium text-foreground" /> lines of code nobody
      will ever read.
    </p>
  )
}
```

## API Reference

### NumberTicker

An animated number. The final value is in the server HTML, in print and for screen readers (which
never hear the frames in between); the count-up is purely visual. It runs once, the first time the
number scrolls into view, and is skipped for reduced motion and for numbers that were already on
screen when a server-rendered page hydrated. Changing `value` later counts from the current number
to the new one. Width is reserved for the wider of `from` and `value`, so nothing around it shifts
(with `compact`, a frame just below a unit, like "999.9K" on the way to "18.4M", can be wider for
a frame or two).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` | — | The number to count to. |
| `from` | `number` | `0` | Where the count starts. |
| `duration` | `number` | `1600` | Animation length in ms. |
| `delay` | `number` | `0` | Delay after entering the viewport, in ms. |
| `locale` | `string` | `"en-US"` | BCP 47 locale for `Intl.NumberFormat`. Fixed to `en-US` by default so the server and the browser render the same text (the runtime default differs between them); pass your site's locale. |
| `decimals` | `number` | `0` | Fraction digits shown (fixed, so the width never changes). |
| `compact` | `boolean` | `false` | Compact notation: 4800 → "4.8K". |
| `formatOptions` | `Intl.NumberFormatOptions` | — | Extra `Intl.NumberFormat` options (currency, percent, units…). |
| `prefix` | `React.ReactNode` | — | Rendered before the number, e.g. "$". Read by screen readers together with the number. |
| `suffix` | `React.ReactNode` | — | Rendered after the number, e.g. "+" or "%". Read by screen readers together with the number. |

Also accepts every `span` prop.



---

# Overlay Menu

> Full-screen menu with a Menu ↔ Close morphing trigger, big numbered links, hover previews and a footer slot.

Category: Navigation · Registry item: `@portfolio-kit/overlay-menu` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/overlay-menu) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/overlay-menu.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/overlay-menu
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/overlay-menu.tsx` and the kit items it uses: `typography`, `use-composed-refs`.

npm dependencies: `class-variance-authority`, `lucide-react`, `radix-ui`.

## Usage

```tsx
import {
  OverlayMenu,
  OverlayMenuContent,
  OverlayMenuFooter,
  OverlayMenuLink,
  OverlayMenuTrigger,
} from "@/components/portfolio/overlay-menu"

<OverlayMenu>
  <header className="flex items-center justify-between">
    <a href="/">Noa Vale</a>
    <OverlayMenuTrigger />
  </header>
  <OverlayMenuContent>
    <OverlayMenuLink href="/work" active>
      Work
    </OverlayMenuLink>
    <OverlayMenuLink href="/about">About</OverlayMenuLink>
    <OverlayMenuFooter>
      <a href="mailto:hello@example.com">hello@example.com</a>
    </OverlayMenuFooter>
  </OverlayMenuContent>
</OverlayMenu>
```

## Examples

### Demo

A full-screen menu with big numbered links, a preview image for the hovered link and a contact footer. Close it to see the page, then reopen it from the Menu pill.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  OverlayMenu,
  OverlayMenuContent,
  OverlayMenuFooter,
  OverlayMenuLink,
  OverlayMenuTrigger,
} from "@/components/portfolio/overlay-menu"
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"
import { typography } from "@/lib/typography"

const links = [
  { label: "Home", href: "#home", art: "landscape" },
  { label: "Work", href: "#work", art: "interface" },
  { label: "About", href: "#about", art: "portrait" },
  { label: "Writing", href: "#writing", art: "bauhaus" },
  { label: "Contact", href: "#contact", art: "rings" },
] as const

export default function OverlayMenuDemo() {
  return (
    <div className="min-h-svh">
      {/* This preview starts with the menu open (without grabbing focus). On a real site, drop `defaultOpen` and `onOpenAutoFocus`. */}
      <OverlayMenu defaultOpen>
        <header className="flex h-16 items-center justify-between px-5 sm:px-6 md:h-20 md:px-8">
          <a
            href="#home"
            className="rounded-md font-heading text-base outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
          >
            Noa Vale
          </a>
          <OverlayMenuTrigger />
        </header>
        <OverlayMenuContent onOpenAutoFocus={(event) => event.preventDefault()}>
          {links.map((link, i) => (
            <OverlayMenuLink
              key={link.href}
              href={link.href}
              active={i === 0}
              preview={<GenerativeArt seed={`menu-${link.label}`} variant={link.art} />}
            >
              {link.label}
            </OverlayMenuLink>
          ))}
          <OverlayMenuFooter>
            <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:gap-6">
              <ArrowLink href="mailto:hello@example.com" className="self-start text-sm sm:self-auto">
                hello@example.com
              </ArrowLink>
              <AvailabilityBadge variant="plain" className="text-muted-foreground" />
            </div>
            <SocialLinks className="-ml-2 sm:-mr-2 sm:ml-0">
              <SocialLink href="https://github.com/example" />
              <SocialLink href="https://x.com/example" />
              <SocialLink href="https://www.linkedin.com/in/example" />
              <SocialLink href="https://dribbble.com/example" />
            </SocialLinks>
          </OverlayMenuFooter>
        </OverlayMenuContent>
      </OverlayMenu>
      <main className="px-5 pt-16 sm:px-6 md:px-8 md:pt-24">
        <p className={typography.eyebrow}>Design Engineer · Lisbon</p>
        <h1 className={`${typography.display} mt-4 max-w-4xl`}>Interfaces that feel inevitable.</h1>
      </main>
    </div>
  )
}
```

### Plain Trigger

`variant="plain"` drops the pill for a bare Menu ↔ Close label; without previews the links take the full width.

```tsx
import {
  OverlayMenu,
  OverlayMenuContent,
  OverlayMenuFooter,
  OverlayMenuLink,
  OverlayMenuTrigger,
} from "@/components/portfolio/overlay-menu"
import { typography } from "@/lib/typography"

const links = [
  { label: "Selected work", href: "#work" },
  { label: "Studio", href: "#studio" },
  { label: "Journal", href: "#journal" },
  { label: "Contact", href: "#contact" },
]

export default function OverlayMenuPlain() {
  return (
    <div className="min-h-svh">
      <OverlayMenu label="Index" closeLabel="Close">
        <header className="flex h-16 items-center justify-between border-b px-5 sm:px-6 md:h-20 md:px-8">
          <a
            href="#top"
            className="rounded-md py-0.5 font-mono text-sm tracking-[0.16em] uppercase outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
          >
            Vale Studio
          </a>
          <OverlayMenuTrigger variant="plain" />
        </header>
        <OverlayMenuContent>
          {links.map((link) => (
            <OverlayMenuLink key={link.href} href={link.href}>
              {link.label}
            </OverlayMenuLink>
          ))}
          <OverlayMenuFooter>
            <p className={typography.meta}>© 2026 Vale Studio</p>
            <p className={typography.meta}>Lisbon, Portugal</p>
          </OverlayMenuFooter>
        </OverlayMenuContent>
      </OverlayMenu>
      <main className="grid gap-6 px-5 pt-16 sm:px-6 md:grid-cols-2 md:px-8 md:pt-24">
        <h1 className={typography.title}>An independent studio for brand and product design.</h1>
        <p className={`${typography.lead} md:pt-2`}>
          We work with a handful of teams each year on identities, websites and the product interfaces behind them.
        </p>
      </main>
    </div>
  )
}
```

## API Reference

### OverlayMenu

Root. Holds state; renders no DOM of its own.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | — | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | — | Called when the menu opens or closes (trigger, Esc, following a link). |
| `label` | `string` | `"Menu"` | Trigger text while closed; also the menu's accessible name. |
| `closeLabel` | `string` | `"Close"` | Trigger text while open; also the close button's accessible name. |
| `children` | `React.ReactNode` | — | `OverlayMenuTrigger` and `OverlayMenuContent`. |

### OverlayMenuTrigger

The Menu button: two lines and a label that morph into × Close. `variant="pill"` is a frosted pill,
`variant="plain"` a bare label. While the menu is open an identical close button sits exactly on top of it.
It announces its expanded state, is 44px tall on phones and is hidden in print.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"pill" \| "plain"` | `"pill"` | `pill`: a bordered, frosted pill that reads on any hero. `plain`: just the label and icon, for minimal headers. |

Also accepts every `button` prop.

### OverlayMenuContent

The full-screen panel, a modal dialog named by the menu's `label`: it traps focus, closes on Esc, locks page
scroll and returns focus to the trigger (or leaves it with the destination after a link is followed).
Put `OverlayMenuLink`s and an optional `OverlayMenuFooter` inside; links are numbered and staggered automatically.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `navLabel` | `string` | `"Main"` | Accessible name of the navigation. |

Also accepts every `Dialog.Content` prop.

### OverlayMenuLink

A big numbered link; closes the menu when followed. The number is decorative (hidden from screen readers). Must be a **direct** child of `<OverlayMenuContent>`
(it reads the list's numbering and previews from there).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `preview` | `React.ReactNode` | — | Shown in the side panel (lg+) while this link is hovered or focused. |
| `active` | `boolean` | — | Marks the current page. |

Also accepts every `a` prop.

### OverlayMenuFooter

Bottom row of the panel for socials, email or availability.

Also accepts every `div` prop.

## Used in templates

- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Page Transition

> View Transitions helpers for any router: `startPageTransition()`, preset animations (fade, slide-up, curtain, zoom) and shared-element names. Instant with reduced motion or without browser support.

Category: Effects · Registry item: `@portfolio-kit/page-transition` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/page-transition) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/page-transition.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/page-transition
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/page-transition.tsx`.

npm dependencies: `radix-ui`.

## Usage

```tsx
import {
  PageTransitionStyles,
  ViewTransitionName,
} from "@/components/portfolio/page-transition"

<div>
  <PageTransitionStyles preset="slide-up" />
  <ViewTransitionName name="cover-lumen" className="aspect-video overflow-hidden rounded-2xl">
    <img src="/lumen.jpg" alt="Lumen dashboard" />
  </ViewTransitionName>
</div>
```

## Examples

### Demo

Switch pages with the fade, slide-up, curtain or zoom preset. The header gets its own `ViewTransitionName`, so it stays put while the page changes.

```tsx
import * as React from "react"
import { flushSync } from "react-dom"

import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  PageTransitionStyles,
  ViewTransitionName,
  startPageTransition,
  type PageTransitionPreset,
} from "@/components/portfolio/page-transition"
import { typography } from "@/lib/typography"

const presets: PageTransitionPreset[] = ["fade", "slide-up", "curtain", "zoom"]

const pages = [
  {
    id: "work",
    label: "Work",
    title: "Calm software for ambitious teams.",
    body: "Design systems, data-dense dashboards and marketing sites — designed and built end to end.",
    art: "interface",
  },
  {
    id: "about",
    label: "About",
    title: "Nine years between design and code.",
    body: "I work at the seam between product design and front-end engineering, from first sketch to production.",
    art: "portrait",
  },
  {
    id: "contact",
    label: "Contact",
    title: "Say hello.",
    body: "Two or three projects a quarter. Write to hello@example.com and I’ll reply within two working days.",
    art: "landscape",
  },
] as const

type PageId = (typeof pages)[number]["id"]

const segment =
  "h-8 rounded-pill px-3.5 text-sm font-medium text-muted-foreground outline-none transition-colors duration-200 hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-[current=page]:bg-background aria-[current=page]:text-foreground aria-[current=page]:shadow-card aria-pressed:bg-background aria-pressed:text-foreground aria-pressed:shadow-card"

export default function PageTransitionDemo() {
  const [preset, setPreset] = React.useState<PageTransitionPreset>("curtain")
  const [pageId, setPageId] = React.useState<PageId>("work")
  const page = pages.find((p) => p.id === pageId) ?? pages[0]

  const go = (next: PageId) => {
    if (next === pageId) return
    startPageTransition(() => flushSync(() => setPageId(next)))
  }

  return (
    <div className="mx-auto flex max-w-4xl flex-col gap-6">
      <PageTransitionStyles preset={preset} />

      <div className="flex flex-col gap-3">
        <p className={typography.meta}>Pick a preset, then switch pages</p>
        <div role="group" aria-label="Transition preset" className="flex w-fit flex-wrap gap-1 rounded-pill border bg-muted/50 p-1">
          {presets.map((p) => (
            <button
              key={p}
              type="button"
              aria-pressed={preset === p}
              onClick={() => setPreset(p)}
              className={cn(segment, "font-mono text-xs")}
            >
              {p}
            </button>
          ))}
        </div>
      </div>

      <div className="overflow-hidden rounded-2xl border bg-background shadow-card">
        <ViewTransitionName
          name="site-header"
          className="flex items-center justify-between gap-4 border-b bg-background px-5 py-3 md:px-6"
        >
          <span className="font-heading text-base">Noa Vale</span>
          <nav aria-label="Pages">
            <ul role="list" className="flex gap-1">
              {pages.map((p) => (
                <li key={p.id}>
                  <button
                    type="button"
                    aria-current={p.id === pageId ? "page" : undefined}
                    onClick={() => go(p.id)}
                    className={segment}
                  >
                    {p.label}
                  </button>
                </li>
              ))}
            </ul>
          </nav>
        </ViewTransitionName>
        <div className="grid gap-6 p-5 md:grid-cols-[1.2fr_1fr] md:items-center md:gap-10 md:p-10">
          <div className="flex flex-col gap-4">
            <p className={typography.eyebrow}>{page.label}</p>
            <h2 className={typography.title}>{page.title}</h2>
            <p className={typography.body}>{page.body}</p>
          </div>
          <div className="aspect-[4/3] overflow-hidden rounded-xl border">
            <GenerativeArt seed={page.id} variant={page.art} />
          </div>
        </div>
      </div>
    </div>
  )
}
```

### Shared elements

Open a project: its cover and title morph into the case-study header through `ViewTransitionName`, the rest of the page slides up, and focus moves to the new heading (and back to the card on return).

```tsx
import * as React from "react"
import { flushSync } from "react-dom"
import { ArrowLeft } from "lucide-react"

import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  PageTransitionStyles,
  ViewTransitionName,
  startPageTransition,
} from "@/components/portfolio/page-transition"
import { typography } from "@/lib/typography"

type Project = (typeof projects)[number]

const projects = [
  {
    slug: "lumen",
    title: "Lumen",
    client: "Halcyon Labs",
    year: 2025,
    role: "Design lead",
    summary: "A design system and component platform powering eleven products and 140 engineers.",
  },
  {
    slug: "tidewater",
    title: "Tidewater",
    client: "Tidewater Energy",
    year: 2025,
    role: "Product design",
    summary: "Real-time grid monitoring for coastal wind farms — dense data, calm interface.",
  },
  {
    slug: "fieldnote",
    title: "Fieldnote",
    client: "Fieldnote Inc.",
    year: 2024,
    role: "Brand & web",
    summary: "Identity and marketing site for a note-taking app built for researchers.",
  },
] as const

const pill =
  "inline-flex h-9 w-fit items-center gap-2 rounded-pill border bg-background px-4 text-sm font-medium outline-none transition-colors duration-200 hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/50"

export default function PageTransitionSharedElement() {
  const [open, setOpen] = React.useState<Project | null>(null)
  const headingRef = React.useRef<HTMLHeadingElement>(null)
  const listRef = React.useRef<HTMLUListElement>(null)

  const navigate = (next: Project | null) => {
    const from = open
    // flushSync makes React commit the new view before the browser snapshots it.
    startPageTransition(() => {
      flushSync(() => setOpen(next))
      window.scrollTo(0, 0)
      // The focused link or button is gone: focus the case-study heading, or the card you came from.
      const target = next
        ? headingRef.current
        : listRef.current?.querySelector<HTMLElement>(`[data-slug="${from?.slug}"]`)
      target?.focus({ preventScroll: true })
    })
  }

  return (
    <div className="mx-auto flex max-w-4xl flex-col gap-8">
      <PageTransitionStyles preset="slide-up" />
      {open ? (
        <article className="flex flex-col gap-8">
          <button type="button" onClick={() => navigate(null)} className={pill}>
            <ArrowLeft aria-hidden className="size-4" />
            All work
          </button>
          <div className="flex flex-col gap-3">
            <p className={typography.eyebrow}>
              {open.client} · {open.role}
            </p>
            <ViewTransitionName name={`title-${open.slug}`} className="w-fit">
              <h2 ref={headingRef} tabIndex={-1} className={cn(typography.display, "outline-none")}>
                {open.title}
              </h2>
            </ViewTransitionName>
          </div>
          <ViewTransitionName name={`cover-${open.slug}`} className="aspect-[21/9] overflow-hidden rounded-2xl border">
            <GenerativeArt seed={open.slug} variant="interface" />
          </ViewTransitionName>
          <p className={cn(typography.lead, "max-w-2xl")}>{open.summary}</p>
        </article>
      ) : (
        <div className="flex flex-col gap-8">
          <div className="flex flex-col gap-3">
            <p className={typography.meta}>Open a project to see the transition</p>
            <h2 className={typography.title}>Selected work</h2>
          </div>
          <ul role="list" ref={listRef} className="grid gap-4 sm:grid-cols-3">
            {projects.map((project) => (
              <li key={project.slug}>
                <a
                  href={`#${project.slug}`}
                  data-slug={project.slug}
                  onClick={(event) => {
                    // Your router's navigation goes here.
                    event.preventDefault()
                    navigate(project)
                  }}
                  className="flex flex-col overflow-hidden rounded-2xl border bg-card shadow-card outline-none transition-colors duration-300 ease-smooth hover:border-border-hover focus-visible:ring-[3px] focus-visible:ring-ring/50"
                >
                  <ViewTransitionName name={`cover-${project.slug}`} className="aspect-[4/3] overflow-hidden border-b">
                    <GenerativeArt seed={project.slug} variant="interface" />
                  </ViewTransitionName>
                  <div className="flex flex-col gap-1 p-5">
                    <span className={typography.meta}>
                      {project.client} · {project.year}
                    </span>
                    <ViewTransitionName name={`title-${project.slug}`} className="w-fit">
                      <h3 className={typography.heading}>{project.title}</h3>
                    </ViewTransitionName>
                  </div>
                </a>
              </li>
            ))}
          </ul>
        </div>
      )}
    </div>
  )
}
```

### Filtered grid

Not just for pages: name every card and wrap the filter change in `startPageTransition()`, and cards glide to their new places while the rest fade in and out.

```tsx
import * as React from "react"
import { flushSync } from "react-dom"

import { FilterChip, FilterChips } from "@/components/portfolio/filter-chips"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  PageTransitionStyles,
  ViewTransitionName,
  startPageTransition,
} from "@/components/portfolio/page-transition"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"

const projects = [
  { slug: "lumen", title: "Lumen", category: "Product", year: 2025 },
  { slug: "fieldnote", title: "Fieldnote", category: "Brand", year: 2024 },
  { slug: "tidewater", title: "Tidewater", category: "Product", year: 2025 },
  { slug: "orbit", title: "Orbit", category: "Open source", year: 2024 },
  { slug: "saltworks", title: "Saltworks", category: "Brand", year: 2023 },
  { slug: "relay", title: "Relay", category: "Open source", year: 2023 },
] as const

const categories = ["All", "Product", "Brand", "Open source"]

export default function PageTransitionFilter() {
  const [category, setCategory] = React.useState("All")
  const visible = category === "All" ? projects : projects.filter((p) => p.category === category)

  const filter = (next: string) => {
    // flushSync commits the new grid before the browser takes its "after" snapshot.
    startPageTransition(() => flushSync(() => setCategory(next)))
  }

  return (
    <div className="mx-auto flex max-w-4xl flex-col gap-6">
      <PageTransitionStyles preset="fade" duration={500} />
      <FilterChips type="single" required value={category} onValueChange={filter} aria-label="Filter by category">
        {categories.map((c) => (
          <FilterChip
            key={c}
            value={c}
            label={c}
            count={c === "All" ? projects.length : projects.filter((p) => p.category === c).length}
          />
        ))}
      </FilterChips>
      <ul role="list" className="grid grid-cols-2 gap-3 sm:grid-cols-3 md:gap-4">
        {visible.map((project) => (
          <li key={project.slug}>
            {/* Same name before and after the filter change, so the card morphs to its new slot. */}
            <ViewTransitionName name={`project-${project.slug}`}>
              <ProjectCard href={`#${project.slug}`}>
                <ProjectCardMedia>
                  <GenerativeArt seed={project.slug} variant="interface" />
                </ProjectCardMedia>
                <ProjectCardContent>
                  <ProjectCardMeta>
                    <span>{project.year}</span>
                    <span>{project.category}</span>
                  </ProjectCardMeta>
                  <ProjectCardTitle>{project.title}</ProjectCardTitle>
                </ProjectCardContent>
              </ProjectCard>
            </ViewTransitionName>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

## API Reference

### PageTransitionStyles

Injects the `::view-transition-*` rules for a preset. Render it once near
the root; swap `preset` at any time. Shared elements tagged with
`<ViewTransitionName>` morph with the same duration and easing.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `preset` | `"fade" \| "slide-up" \| "curtain" \| "zoom"` | `"fade"` | How the old page hands over to the new one: `fade` cross-fades, `slide-up` lifts the new page in, `curtain` wipes the new page up over the old one, `zoom` scales through. |
| `duration` | `number` | — | Duration in ms. Defaults per preset: fade 350, slide-up 550, zoom 500, curtain 900. |
| `easing` | `string` | — | Any CSS easing. Defaults to the kit's ease-smooth (curtain uses an in-out curve). |
| `nonce` | `string` | — | CSP nonce for the injected `<style>` tag, if your Content-Security-Policy requires one. |

### ViewTransitionName

Tags an element for a shared-element morph between two views: render the
same `name` on the old and new element and the browser animates between them.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Unique name shared by the "before" and "after" element, e.g. `project-${slug}`. |
| `asChild` | `boolean` | — | Merge onto the single child instead of wrapping it in a div. |

Also accepts every `div` prop.



---

# Parallax

> Scroll-linked depth: layers that drift slower or faster than the page, and media that glides inside its frame. One shared animation frame, paused offscreen, still with reduced motion and in print.

Category: Effects · Registry item: `@portfolio-kit/parallax` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/parallax) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/parallax.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/parallax
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/parallax.tsx` and the kit items it uses: `use-composed-refs`, `use-reduced-motion`.

## Usage

```tsx
import { ParallaxMedia } from "@/components/portfolio/parallax"

<ParallaxMedia strength={0.15} zoom={1.1} className="aspect-[16/10] rounded-2xl border">
  <img src="/platform.jpg" alt="Departure board on a station platform" />
</ParallaxMedia>
```

## Examples

### Demo

A photographer’s gallery where each column scrolls at its own speed, so a plain grid of images gains depth without any extra markup per image. Scroll the preview.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Parallax } from "@/components/portfolio/parallax"
import { typography } from "@/lib/typography"

const columns = [
  {
    // Negative: starts a little low and rises faster than the page, so it feels closest.
    speed: -0.1,
    photos: [
      { seed: "fjord-morning", variant: "landscape", caption: "Fjord, 06:10" },
      { seed: "harbour-keeper", variant: "portrait", caption: "The harbour keeper" },
      { seed: "harbour-lights", variant: "landscape", caption: "Harbour lights" },
    ],
  },
  {
    // Positive: lags behind the scroll, so the middle column feels furthest away.
    speed: 0.12,
    photos: [
      { seed: "salt-marsh", variant: "landscape", caption: "Salt marsh" },
      { seed: "ferry-captain", variant: "portrait", caption: "Captain, Lisbon ferry" },
      { seed: "last-ferry", variant: "landscape", caption: "Last ferry" },
    ],
  },
  {
    speed: -0.18,
    photos: [
      { seed: "tram-driver", variant: "portrait", caption: "Tram 43, driver" },
      { seed: "glasshouse", variant: "landscape", caption: "Glasshouse" },
      { seed: "north-light", variant: "landscape", caption: "North light" },
    ],
  },
] as const

export default function ParallaxDemo() {
  return (
    <section className="overflow-hidden px-5 py-20 sm:px-6 md:px-8 md:py-28">
      <div className="mx-auto flex max-w-5xl flex-col gap-12 md:gap-16">
        <header className="flex flex-col gap-4">
          <p className={typography.eyebrow}>Photographs · 2023–2026</p>
          <h2 className={typography.title}>Coastlines &amp; faces</h2>
        </header>
        <div className="grid grid-cols-3 gap-3 md:gap-6">
          {columns.map((column, i) => (
            <Parallax key={column.photos[0].seed} speed={column.speed} max={96} className={i === 1 ? "mt-12 md:mt-24" : undefined}>
              <ul role="list" className="flex flex-col gap-3 md:gap-6">
                {column.photos.map((photo) => (
                  <li key={photo.seed}>
                    <figure className="flex flex-col gap-2">
                      <GenerativeArt
                        seed={photo.seed}
                        variant={photo.variant}
                        label={photo.caption}
                        className="aspect-[3/4] overflow-hidden rounded-xl border"
                      />
                      <figcaption className={`${typography.meta} hidden sm:block`}>{photo.caption}</figcaption>
                    </figure>
                  </li>
                ))}
              </ul>
            </Parallax>
          ))}
        </div>
      </div>
    </section>
  )
}
```

### Layers

A hero with depth: shapes at different speeds around a headline, and a line of type that slides sideways with `axis="x"`.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Parallax } from "@/components/portfolio/parallax"
import { typography } from "@/lib/typography"

export default function ParallaxLayers() {
  return (
    <div className="overflow-hidden">
      <section className="relative flex min-h-[760px] flex-col items-center justify-center gap-6 px-6 py-24 text-center">
        {/* Far away: lags behind the scroll. */}
        <Parallax speed={0.35} className="absolute top-16 left-[6%] size-28 md:size-40" aria-hidden>
          <GenerativeArt seed="far" variant="orb" className="rounded-full" grain={false} />
        </Parallax>
        {/* Close: runs ahead of the scroll and grows. */}
        <Parallax speed={-0.25} scale={[0.9, 1.1]} className="absolute right-[8%] bottom-24 size-24 md:size-36" aria-hidden>
          <GenerativeArt seed="near" variant="bauhaus" className="rounded-2xl" grain={false} />
        </Parallax>
        <Parallax speed={0.15} className="absolute top-1/3 right-[14%] hidden size-16 md:block" aria-hidden>
          <GenerativeArt seed="mid" variant="rings" className="rounded-full" grain={false} />
        </Parallax>
        <p className={typography.eyebrow}>Motion &amp; interface design</p>
        <h1 className={`${typography.display} relative max-w-4xl`}>Interfaces with a sense of depth</h1>
        <Parallax axis="x" speed={0.4} className="mt-6 w-full" aria-hidden>
          <p className="font-heading text-3xl whitespace-nowrap text-muted-foreground md:text-5xl">
            Motion · Systems · Prototypes · Motion · Systems · Prototypes
          </p>
        </Parallax>
      </section>
      <section className="mx-auto max-w-xl px-6 pb-40">
        <p className={typography.lead}>
          Scroll back up: the far shape lags, the near one runs ahead and grows, and the line of type slides across.
        </p>
      </section>
    </div>
  )
}
```

### Media in a frame

`ParallaxMedia` glides case-study images inside their frames as you scroll, so big images feel like windows rather than stickers.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { ParallaxMedia } from "@/components/portfolio/parallax"
import { typography } from "@/lib/typography"

export default function ParallaxMediaExample() {
  return (
    <article className="mx-auto flex max-w-4xl flex-col gap-12 px-5 py-20 sm:px-6 md:gap-16 md:px-8">
      <header className="flex flex-col gap-4">
        <p className={typography.eyebrow}>Case study · 2026</p>
        <h1 className={typography.title}>Northwind Rail — a timetable you can read at a glance</h1>
      </header>
      <ParallaxMedia strength={0.15} className="aspect-[16/10] rounded-2xl border">
        <GenerativeArt seed="northwind-platform" variant="interface" />
      </ParallaxMedia>
      <p className={typography.lead}>
        Commuters check the board for four seconds. We rebuilt the departure screens around that number: one typeface, three sizes
        and a colour for every line, tested on platforms at rush hour.
      </p>
      <div className="grid gap-6 sm:grid-cols-2">
        <ParallaxMedia strength={0.2} zoom={1.12} className="aspect-[4/5] rounded-2xl border">
          <GenerativeArt seed="northwind-type" variant="interface" />
        </ParallaxMedia>
        <ParallaxMedia strength={0.1} className="aspect-[4/5] rounded-2xl border sm:mt-24">
          <GenerativeArt seed="northwind-night" variant="landscape" />
        </ParallaxMedia>
      </div>
      <p className={typography.lead}>
        The result shipped to 212 stations in nine months, and complaints about missed connections dropped by a third.
      </p>
    </article>
  )
}
```

## API Reference

### Parallax

A layer that moves at its own speed while the page scrolls. Style and position it with `className`
(e.g. `absolute right-8 top-10`); the inner `parallax-layer` is what moves. Reduced motion and print
render it still, in its normal place. A moving layer can leave its section (sideways with `axis="x"`),
so clip the section with `overflow-hidden` (or `overflow-clip`, which keeps sticky children working)
and the page never scrolls sideways.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `speed` | `number` | `0.2` | How far the layer drifts, as a fraction of its travel through the viewport. Positive values lag behind the scroll (feel further away), negative values run ahead (feel closer). `0.1`–`0.3` is subtle. |
| `axis` | `"x" \| "y"` | `"y"` | Direction of the drift. `x` slides sideways as you scroll, for marquee-like headlines. |
| `scale` | `[number, number]` | — | Scale while scrolling through: `[entering, leaving]`, e.g. `[0.9, 1.05]`. |
| `max` | `number` | `240` | Maximum offset in px, so tall layers or large speeds never fly off. |
| `disabled` | `boolean` | `false` | Turn the effect off (it's already off with reduced motion). |

Also accepts every `div` prop.

### ParallaxMedia

A clipping frame whose image (or `<GenerativeArt />`, `<video>`) glides slower than the page.
Give it a shape with `className` (`aspect-video rounded-2xl`…). Reduced motion and print show the media centered and still.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `strength` | `number` | `0.12` | How far the media glides inside its frame, as a fraction of the frame's height (`0`–`0.3`). The media is enlarged by the same amount on each side, so no edge ever shows. |
| `zoom` | `number` | `1` | Extra zoom (`1` or more) that settles to 1 as the frame reaches the viewport center, e.g. `1.15`. |
| `disabled` | `boolean` | `false` | Turn the effect off (it's already off with reduced motion). |

Also accepts every `div` prop.



---

# Photo Meta

> EXIF-style caption for photographs and film stills (camera, lens, focal length, aperture, shutter, ISO, place and date) as a mono line, a spec grid or an overlay on the image.

Category: Work · Registry item: `@portfolio-kit/photo-meta` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/photo-meta) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/photo-meta.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/photo-meta
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/photo-meta.tsx` and the kit items it uses: `format`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  PhotoMeta,
  PhotoMetaItem,
} from "@/components/portfolio/photo-meta"

<PhotoMeta camera="Fujifilm X100V" focal={23} aperture={2} shutter="1/250" iso={400} date="2026-06-14">
  <PhotoMetaItem label="Film simulation">Classic Chrome</PhotoMetaItem>
</PhotoMeta>
```

## Examples

### Demo

A landscape with its shooting data as one mono caption line: body, lens, focal length, aperture, shutter, ISO, place and date.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Media } from "@/components/portfolio/media"
import { PhotoMeta } from "@/components/portfolio/photo-meta"

export default function PhotoMetaDemo() {
  return (
    <Media
      ratio="video"
      className="w-lg max-w-full"
      caption={
        <PhotoMeta
          camera="Fujifilm X-T5"
          lens="XF 33mm F1.4"
          focal={33}
          aperture={2.8}
          shutter="1/250"
          iso={400}
          place="Hvalfjörður, Iceland"
          date="2026-06-14"
        />
      }
    >
      <GenerativeArt seed="hvalfjordur" variant="landscape" label="A fjord under a pale midnight sun" />
    </Media>
  )
}
```

### Spec sheet

A feature image with a labelled grid of its settings beside it, plus custom rows for film stock and development.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Media } from "@/components/portfolio/media"
import { PhotoMeta, PhotoMetaItem } from "@/components/portfolio/photo-meta"
import { typography } from "@/lib/typography"

export default function PhotoMetaGrid() {
  return (
    <figure className="grid w-3xl max-w-full gap-6 md:grid-cols-[3fr_2fr] md:items-end">
      <Media ratio="tall">
        <GenerativeArt seed="westfjords-blue-hour" variant="landscape" label="Ridgelines fading into blue-hour haze" />
      </Media>
      <figcaption className="flex flex-col gap-5">
        <div className="flex flex-col gap-1.5">
          <h3 className={typography.heading}>Ridgelines at blue hour</h3>
          <p className={typography.body}>Westfjords, twenty minutes after the sun dipped below the sea.</p>
        </div>
        <PhotoMeta
          variant="grid"
          camera="Leica M6"
          lens="Summicron 50 f/2"
          focal={50}
          aperture="f/4"
          shutter="1/125"
          place="Ísafjörður, Iceland"
          date="2025-09-21"
          datePreset="long"
        >
          <PhotoMetaItem label="Film">Kodak Portra 400</PhotoMetaItem>
          <PhotoMetaItem label="Developed">Push +1, at home</PhotoMetaItem>
        </PhotoMeta>
      </figcaption>
    </figure>
  )
}
```

### Overlay

The settings in white over the bottom of the photo, on a dark scrim that keeps them readable on bright skies in light and dark mode.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Media } from "@/components/portfolio/media"
import { PhotoMeta } from "@/components/portfolio/photo-meta"

export default function PhotoMetaOverlay() {
  return (
    <figure className="relative w-sm max-w-full overflow-hidden rounded-xl">
      <Media ratio="portrait" radius="none">
        <GenerativeArt seed="dunes-in-fog" variant="landscape" label="Dunes fading into fog" />
      </Media>
      <figcaption>
        <PhotoMeta
          variant="overlay"
          camera="Leica Q3"
          focal={28}
          aperture={8}
          shutter={0.002}
          iso={100}
          place="Comporta"
          date="2026-01-09"
        />
      </figcaption>
    </figure>
  )
}
```

## API Reference

### PhotoMeta

A `<dl>` of shooting data. Pass the fields you have (empty ones are skipped) and add your own
`<PhotoMetaItem>`s as children; they come after the built-in fields. Put it in a `<figcaption>`
(or the `caption` of `Media` or `LightboxTrigger`) to tie it to its photo.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"line" \| "grid" \| "overlay"` | `"line"` | `line`: one compact mono line with dot separators, for a caption under the photo. `grid`: a labelled spec sheet in columns, beside or under a feature image. `overlay`: the line in white on a dark scrim, pinned to the bottom of the nearest positioned parent (an image frame). |
| `camera` | `React.ReactNode` | — | Camera body, e.g. "Leica M6" or "Fujifilm X100V". |
| `lens` | `React.ReactNode` | — | Lens, e.g. "Summicron 35 f/2". |
| `focal` | `number \| string \| readonly [number, number]` | — | Focal length in millimetres: `35`, `"35mm"`, or a zoom range `[24, 70]` → "24–70 mm". |
| `aperture` | `number \| string` | — | f-number: `1.8`, `"1.8"` or `"f/1.8"` → "ƒ/1.8" (announced as "f/1.8"). |
| `shutter` | `number \| string` | — | Exposure time. Numbers are seconds (`0.004` → "1/250 s", `30` → "30 s"); strings like `"1/250"` work too. |
| `iso` | `number \| string` | — | Sensitivity: `400` or `"ISO 400"` → "ISO 400" in `line`/`overlay`, "400" under the ISO label in `grid`. |
| `place` | `React.ReactNode` | — | Where it was taken, e.g. "Hvalfjörður, Iceland". |
| `date` | `DateInput` | — | When it was taken: a `Date`, ISO string (`"2026-06-14"`) or timestamp. Rendered as `<time>`. |
| `datePreset` | `"year" \| "full" \| "month-year" \| "short" \| "long" \| "short-padded" \| "full-padded"` | `"full"` | `formatDate` preset for `date`: `full` "Jun 14, 2026", `long`, `month-year` "Jun 2026"… |
| `locale` | `string` | `"en-US"` | BCP 47 locale for the date (default `en-US`, so server and browser render the same text). |
| `labels` | `Partial<PhotoMetaLabels>` | — | Translate or rename the labels: `{ place: "Lieu", focal: "Focale" }`. Labels are visible in `grid` and read by screen readers in every variant. The unit words screen readers hear go here too: `millimetres`, `to` ("24 to 70 millimetres"), `ofASecond` ("1/250 of a second"), `second` and `seconds`. |

Also accepts every `dl` prop.

### PhotoMetaItem

One label/value pair (`<dt>` + `<dd>`), for anything the built-in fields don't cover: film stock, flash, edit.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `React.ReactNode` | — | The term (`<dt>`), e.g. "Film stock". Hidden visually in `line` and `overlay`, but always read by screen readers. |

Also accepts every `div` prop.

### type PhotoMetaLabels

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `date` (required) | `string` | — |  |
| `camera` (required) | `string` | — |  |
| `lens` (required) | `string` | — |  |
| `focal` (required) | `string` | — |  |
| `aperture` (required) | `string` | — |  |
| `shutter` (required) | `string` | — |  |
| `iso` (required) | `string` | — |  |
| `place` (required) | `string` | — |  |
| `millimetres` (required) | `string` | — |  |
| `to` (required) | `string` | — |  |
| `ofASecond` (required) | `string` | — |  |
| `second` (required) | `string` | — |  |
| `seconds` (required) | `string` | — |  |



---

# Photo Stack

> A pile of 3–5 photos that fans out on hover or keyboard focus. Click, tap or press Enter to send the top photo to the back.

Category: About · Registry item: `@portfolio-kit/photo-stack` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/photo-stack) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/photo-stack.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/photo-stack
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/photo-stack.tsx` and the kit items it uses: `media`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  PhotoStack,
  PhotoStackItem,
} from "@/components/portfolio/photo-stack"

<PhotoStack label="Life outside work">
  <PhotoStackItem src="/film.jpg" alt="Film camera on a windowsill" caption="Shooting colour film on weekends." />
  <PhotoStackItem src="/river.jpg" alt="Morning run by the river" caption="5k along the river, most mornings." />
  <PhotoStackItem src="/desk.jpg" alt="Desk with sketches" caption="Where the systems get drawn first." />
</PhotoStack>
```

## Examples

### Demo

A pile of personal photos. Hover or focus to fan them out; click or press Enter to deal the next one.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { PhotoStack, PhotoStackItem } from "@/components/portfolio/photo-stack"

export default function PhotoStackDemo() {
  return (
    <div className="px-6 py-12 sm:px-24">
      <PhotoStack label="Life outside work">
        <PhotoStackItem alt="Hills at sunset, shot on colour film" tilt={-3} caption="Shooting colour film on weekends.">
          <GenerativeArt seed="stack-film" variant="landscape" />
        </PhotoStackItem>
        <PhotoStackItem alt="Morning sky over the river path" tilt={9} caption="5k along the river, most mornings.">
          <GenerativeArt seed="stack-river-run" variant="landscape" />
        </PhotoStackItem>
        <PhotoStackItem alt="Self-portrait in the studio" tilt={-10} caption="The studio, on a good day.">
          <GenerativeArt seed="stack-self" variant="portrait" />
        </PhotoStackItem>
        <PhotoStackItem alt="Generative print pinned to a wall" tilt={5} caption="Generative prints for friends.">
          <GenerativeArt seed="stack-art" variant="rings" />
        </PhotoStackItem>
      </PhotoStack>
    </div>
  )
}
```

### Landscape

Three landscape photos without a caption. Set `ratio` and widen the stack with `className` for travel or event shots.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { PhotoStack, PhotoStackItem } from "@/components/portfolio/photo-stack"

export default function PhotoStackLandscape() {
  return (
    <div className="px-6 py-12 sm:px-24">
      <PhotoStack label="Conference trip" ratio="photo" showCaption={false} className="w-60 sm:w-72">
        <PhotoStackItem alt="Mountains on the drive to the conference">
          <GenerativeArt seed="trip-drive" variant="landscape" />
        </PhotoStackItem>
        <PhotoStackItem alt="Keynote slides on the big screen">
          <GenerativeArt seed="trip-keynote" variant="interface" />
        </PhotoStackItem>
        <PhotoStackItem alt="Workshop wall covered in sticky notes">
          <GenerativeArt seed="trip-workshop" variant="bauhaus" />
        </PhotoStackItem>
      </PhotoStack>
    </div>
  )
}
```

### Beside Text

The stack as the personal touch of an about section, beside a short “off the clock” paragraph.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { PhotoStack, PhotoStackItem } from "@/components/portfolio/photo-stack"
import { Section, SectionEyebrow, SectionHeader, SectionTitle } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

export default function PhotoStackBesideText() {
  return (
    <Section spacing="sm">
      <div className="grid items-center gap-16 md:grid-cols-2 md:gap-12">
        <SectionHeader>
          <SectionEyebrow>Off the clock</SectionEyebrow>
          <SectionTitle className="md:text-4xl">Film, running and too many sketchbooks</SectionTitle>
          <p className={typography.lead}>
            Away from the screen I shoot expired film, run the river path most mornings and draw everything before I
            build it. Click the pile to flip through.
          </p>
        </SectionHeader>
        <PhotoStack label="Life outside work" ratio="square" className="md:w-64">
          <PhotoStackItem alt="Golden-hour hills from the studio roof" caption="Golden hour from the studio roof.">
            <GenerativeArt seed="stack-studio" variant="landscape" />
          </PhotoStackItem>
          <PhotoStackItem alt="Self-portrait on expired film" caption="Self-portrait on expired film.">
            <GenerativeArt seed="stack-film" variant="portrait" />
          </PhotoStackItem>
          <PhotoStackItem alt="Morning sky over the river path" caption="5k along the river, most mornings.">
            <GenerativeArt seed="stack-river" variant="landscape" />
          </PhotoStackItem>
        </PhotoStack>
      </div>
    </Section>
  )
}
```

## API Reference

### PhotoStack

The pile: one button that deals the next photo. Pass `PhotoStackItem`s as **direct**
children (3–5 look best). Size it with `className` (default `w-44` → `md:w-56`).

The photos fan out on hover (mouse and trackpad only, so taps don't leave it stuck open) and
on keyboard focus, where the top photo carries the focus ring. Click, tap, Enter or Space deals
the next photo. With reduced motion the pile changes instantly instead of animating. Leave
some room around it: fanned photos and their shadows reach past its box.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | `"portrait" \| "tall" \| "photo" \| "square"` | `"portrait"` | Shape of every photo: `portrait` 4:5, `tall` 3:4, `photo` 4:3 or `square`. |
| `label` | `string` | `"Photos"` | What the pile is, e.g. "Life outside work". The button is announced as "<label>: show next photo". |
| `labels` | `Partial<{ next: string; position: string }>` | — | Built-in screen-reader text, for translations: `next` (the button's action after the label) and `position` ("Photo {index} of {count}", read before the photo's description). |
| `showCaption` | `boolean` | `true` | Show the top photo's caption under the stack. When off, the photo is still announced to screen readers. |
| `onIndexChange` | `(index: number) => void` | — | Called with the (source-order) index of the photo that comes to the top. |

Also accepts every `div` prop.

### PhotoStackItem

One photo in the pile: an image (`src`) or artwork as children, in a thin card mat.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alt` (required) | `string` | — | Describes the photo, e.g. "Morning sky over the river path". Required: screen readers hear it, with its position ("Photo 2 of 4"), when the photo reaches the top, with or without a visible caption. |
| `src` | `string` | — | Image URL. |
| `caption` | `React.ReactNode` | — | Shown under the stack while this photo is on top. |
| `tilt` | `number` | — | Override the resting tilt in degrees. |
| `children` | `React.ReactNode` | — | Artwork (e.g. <GenerativeArt />) used instead of `src`. |

Also accepts every `div` prop.



---

# Pill Nav

> Segmented navigation with a sliding pill that follows the pointer and rests on the current page.

Category: Navigation · Registry item: `@portfolio-kit/pill-nav` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/pill-nav) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/pill-nav.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/pill-nav
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/pill-nav.tsx`.

npm dependencies: `class-variance-authority`, `radix-ui`.

## Usage

```tsx
import { PillNav, PillNavItem } from "@/components/portfolio/pill-nav"

<PillNav value="/work">
  <PillNavItem href="/">Home</PillNavItem>
  <PillNavItem href="/work">Work</PillNavItem>
  <PillNavItem href="/about">About</PillNavItem>
  <PillNavItem href="/contact">Contact</PillNavItem>
</PillNav>
```

## Examples

### Demo

A segmented nav whose pill glides after the pointer and settles back on the current page.

```tsx
import * as React from "react"

import { PillNav, PillNavItem } from "@/components/portfolio/pill-nav"

const links = [
  { label: "Home", href: "#home" },
  { label: "Work", href: "#work" },
  { label: "About", href: "#about" },
  { label: "Writing", href: "#writing" },
  { label: "Contact", href: "#contact" },
]

export default function PillNavDemo() {
  // In an app, derive this from the router (e.g. the current pathname).
  const [current, setCurrent] = React.useState("#home")

  return (
    <div className="flex w-full max-w-2xl items-center justify-between gap-4 rounded-pill border bg-card p-1.5 shadow-card sm:pl-5">
      <span className="font-heading max-sm:hidden">Noa Vale</span>
      <PillNav value={current}>
        {links.map((link) => (
          <PillNavItem
            key={link.href}
            href={link.href}
            onClick={(event) => {
              event.preventDefault()
              setCurrent(link.href)
            }}
          >
            {link.label}
          </PillNavItem>
        ))}
      </PillNav>
    </div>
  )
}
```

### With Icons

Put a lucide icon before each label. It is sized and aligned for you.

```tsx
import * as React from "react"
import { BookOpen, Briefcase, Home, Mail, User } from "lucide-react"

import { PillNav, PillNavItem } from "@/components/portfolio/pill-nav"

const links = [
  { label: "Home", href: "#home", icon: Home },
  { label: "Work", href: "#work", icon: Briefcase },
  { label: "About", href: "#about", icon: User },
  { label: "Writing", href: "#writing", icon: BookOpen },
  { label: "Contact", href: "#contact", icon: Mail },
]

export default function PillNavWithIcons() {
  const [current, setCurrent] = React.useState("#work")

  return (
    <PillNav value={current}>
      {links.map(({ label, href, icon: Icon }) => (
        <PillNavItem
          key={href}
          href={href}
          onClick={(event) => {
            event.preventDefault()
            setCurrent(href)
          }}
        >
          <Icon aria-hidden />
          {label}
        </PillNavItem>
      ))}
    </PillNav>
  )
}
```

### In a Header

The `ghost` variant drops the track so the nav sits lightly in a header bar. On narrow screens it scrolls sideways and keeps the current page in view.

```tsx
import * as React from "react"

import { PillNav, PillNavItem } from "@/components/portfolio/pill-nav"

const links = [
  { label: "Work", href: "#work" },
  { label: "About", href: "#about" },
  { label: "Writing", href: "#writing" },
  { label: "Contact", href: "#contact" },
]

export default function PillNavInHeader() {
  const [current, setCurrent] = React.useState("#about")

  return (
    <header className="flex h-16 items-center justify-between gap-4 border-b px-5 md:px-8">
      <a
        href="#top"
        className="shrink-0 rounded-md font-heading text-base outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
      >
        Noa Vale
      </a>
      <PillNav variant="ghost" value={current}>
        {links.map((link) => (
          <PillNavItem
            key={link.href}
            href={link.href}
            onClick={(event) => {
              event.preventDefault()
              setCurrent(link.href)
            }}
          >
            {link.label}
          </PillNavItem>
        ))}
      </PillNav>
    </header>
  )
}
```

## API Reference

### PillNav

The nav and its track. `variant="default"` sits on a muted track; `variant="ghost"` has no track, for headers.
On narrow screens it scrolls sideways (with a fade on the clipped side) and keeps the current item in view.
`aria-label` defaults to "Main"; pass your own to translate it or to tell two navs apart.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "ghost"` | `"default"` | `default`: items in a muted track with a raised pill. `ghost`: no track; the pill is a muted fill, for busy headers. |
| `value` | `string` | — | Value of the current item. The pill rests on it. |

Also accepts every `nav` prop.

### PillNavItem

A link in the nav. An icon placed before the label is sized for you. Renders its own `<li>`.
The current item is marked with `aria-current="page"`; the pill itself is decoration.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Compared with `PillNav`'s `value` to mark the current page. Defaults to `href`; set it when you use `asChild`. |
| `asChild` | `boolean` | — | Render your router's link (e.g. Next.js `<Link>`) as the child. |

Also accepts every `a` prop.



---

# Portrait

> A personal photo as a matted frame, tilted polaroid, arch or circle, with a subtle hover effect.

Category: About · Registry item: `@portfolio-kit/portrait` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/portrait) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/portrait.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/portrait
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/portrait.tsx` and the kit items it uses: `media`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { Portrait, portraitVariants } from "@/components/portfolio/portrait"
```

## Examples

### Demo

A matted frame with a mono “Fig.” caption: the default way to show a portrait on an about page.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Portrait } from "@/components/portfolio/portrait"

export default function PortraitDemo() {
  return (
    <Portrait label="Fig. 1" caption="Noa in the studio, Lisbon 2025." className="w-72 sm:w-80">
      <GenerativeArt seed="portrait-noa" variant="portrait" label="Portrait of Noa" />
    </Portrait>
  )
}
```

### Polaroid

An instant-film card resting at a tilt with a handwritten-style caption; it straightens on hover.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Portrait } from "@/components/portfolio/portrait"

export default function PortraitPolaroid() {
  return (
    <div className="p-6">
      <Portrait variant="polaroid" caption="lisbon, summer '25" className="w-64 sm:w-72">
        <GenerativeArt seed="portrait-polaroid" variant="portrait" label="Snapshot of Noa on a rooftop" />
      </Portrait>
    </div>
  )
}
```

### Arch

An arched crop with an offset outline that settles on hover. Pairs well with serif headings.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Portrait } from "@/components/portfolio/portrait"

export default function PortraitArch() {
  return (
    <div className="p-4">
      <Portrait variant="arch" label="Fig. 2" caption="On the river, early morning." className="w-64 sm:w-72">
        <GenerativeArt seed="portrait-arch" variant="portrait" label="Portrait of Noa by the river" />
      </Portrait>
    </div>
  )
}
```

### Circle

A round headshot with a concentric hairline ring, small enough for a hero, sidebar or contact card.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Portrait } from "@/components/portfolio/portrait"

export default function PortraitCircle() {
  return (
    <div className="p-4">
      <Portrait variant="circle" caption="Noa Vale — Design Engineer" className="w-56 sm:w-64">
        <GenerativeArt seed="portrait-circle" variant="portrait" label="Headshot of Noa Vale" />
      </Portrait>
    </div>
  )
}
```

## API Reference

### Portrait

A single portrait photo in one of four presentations. Renders a `<figure>`, with the caption
in a `<figcaption>`. Hover effects need a mouse or trackpad and stay still with reduced motion.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"circle" \| "frame" \| "polaroid" \| "arch" \| null` | `"frame"` | `frame`: a passe-partout mat with a mono caption. `polaroid`: a white instant-film card at a tilt. `arch`: an arched crop with an offset outline. `circle`: a round headshot. |
| `src` | `string` | — | Image URL. The frame keeps its ratio while it loads, so nothing shifts. |
| `alt` | `string` | — | Describes the photo, e.g. "Noa laughing at her desk in the studio". Say what the photo shows rather than "photo of"; leave it empty only when the same words sit right next to it (then the image is decorative). |
| `children` | `React.ReactNode` | — | Artwork (e.g. `<GenerativeArt label="…" />`) used instead of `src`. Give it its own accessible label. |
| `caption` | `React.ReactNode` | — | Caption under the image. Set in the heading face on the polaroid, mono elsewhere. |
| `label` | `React.ReactNode` | — | Figure label shown before the caption in the highlight color, e.g. "Fig. 1". Not used by `polaroid`. |
| `ratio` | `MediaProps["ratio"]` | — | Image ratio. Defaults per variant: `portrait` 4:5 (frame), `square` (polaroid), `tall` 3:4 (arch); `circle` is always square. `auto` follows the photo's own shape (pass `width`/`height` in `imgProps` so nothing shifts). |
| `tilt` | `number` | — | Resting rotation of the polaroid, in degrees (default -3). Leave a little room around it for the tilted corners and shadow. |
| `imgProps` | `MediaProps["imgProps"]` | — | Extra props for the `<img>` (e.g. `loading="eager"`, `sizes`). |

Also accepts every `figure` prop.

## Used in templates

- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Post Card

> Article card with cover, category, title, excerpt, date, reading time and author, in vertical, horizontal or large overlay styles.

Category: Content · Registry item: `@portfolio-kit/post-card` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/post-card) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/post-card.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/post-card
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/post-card.tsx` and the kit items it uses: `format`, `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  PostCard,
  PostCardContent,
  PostCardExcerpt,
  PostCardEyebrow,
  PostCardMedia,
  PostCardMeta,
  PostCardTitle,
} from "@/components/portfolio/post-card"

<PostCard href="/notes/motion-with-intent">
  <PostCardMedia>
    <img src="/motion-with-intent.jpg" alt="" />
  </PostCardMedia>
  <PostCardContent>
    <PostCardEyebrow>Motion</PostCardEyebrow>
    <PostCardTitle>Motion with intent</PostCardTitle>
    <PostCardExcerpt>Animation should answer a question the user just asked.</PostCardExcerpt>
    <PostCardMeta date="2026-02-18" readingTime="7 min" />
  </PostCardContent>
</PostCard>
```

## Examples

### Demo

An article card with cover, category, excerpt, date, reading time and author. The whole card is one link.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  PostCard,
  PostCardAuthor,
  PostCardContent,
  PostCardExcerpt,
  PostCardEyebrow,
  PostCardMedia,
  PostCardMeta,
  PostCardTitle,
} from "@/components/portfolio/post-card"

export default function PostCardDemo() {
  return (
    <PostCard href="#motion-with-intent" className="w-full max-w-sm">
      <PostCardMedia>
        <GenerativeArt seed="motion-with-intent" variant="interface" />
      </PostCardMedia>
      <PostCardContent>
        <PostCardEyebrow>Motion</PostCardEyebrow>
        <PostCardTitle>Motion with intent</PostCardTitle>
        <PostCardExcerpt>
          Animation should answer a question the user just asked. A field guide to motion that informs instead of performs.
        </PostCardExcerpt>
        <PostCardMeta date="2026-02-18" readingTime="7 min" />
        <PostCardAuthor name="Noa Vale" />
      </PostCardContent>
    </PostCard>
  )
}
```

### Horizontal

Cover beside the text from `sm` up, for a “latest post” slot or a single-column blog index.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  PostCard,
  PostCardContent,
  PostCardExcerpt,
  PostCardEyebrow,
  PostCardMedia,
  PostCardMeta,
  PostCardTitle,
} from "@/components/portfolio/post-card"

export default function PostCardHorizontal() {
  return (
    <PostCard variant="horizontal" href="#tokens-are-an-api" className="mx-auto max-w-3xl">
      <PostCardMedia>
        <GenerativeArt seed="tokens-are-an-api" variant="interface" />
      </PostCardMedia>
      <PostCardContent>
        <PostCardEyebrow>Design systems</PostCardEyebrow>
        <PostCardTitle>Tokens are an API</PostCardTitle>
        <PostCardExcerpt>
          Treat tokens like a public API: semver, deprecation windows and codemods kept eleven product teams shipping.
        </PostCardExcerpt>
        <PostCardMeta date="2025-12-09" readingTime="11 min" />
      </PostCardContent>
    </PostCard>
  )
}
```

### Featured

A large card with the text over the cover, to lead a writing page with one post.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  PostCard,
  PostCardAuthor,
  PostCardContent,
  PostCardExcerpt,
  PostCardEyebrow,
  PostCardMedia,
  PostCardMeta,
  PostCardTitle,
} from "@/components/portfolio/post-card"

export default function PostCardFeatured() {
  return (
    <PostCard variant="featured" href="#the-case-for-boring-navigation" className="mx-auto max-w-5xl">
      <PostCardMedia>
        <GenerativeArt seed="boring-navigation" variant="landscape" />
      </PostCardMedia>
      <PostCardContent>
        <PostCardEyebrow>Essay</PostCardEyebrow>
        <PostCardTitle as="h2">The case for boring navigation</PostCardTitle>
        <PostCardExcerpt>
          Clever navigation is a tax on every visit. Why the most predictable menu is usually the right one.
        </PostCardExcerpt>
        <PostCardMeta date="2026-01-27" readingTime="9 min" />
        <PostCardAuthor name="Noa Vale" />
      </PostCardContent>
    </PostCard>
  )
}
```

### Magazine

Mix the variants: one featured story on top, a row of vertical cards below.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  PostCard,
  PostCardContent,
  PostCardExcerpt,
  PostCardEyebrow,
  PostCardMedia,
  PostCardMeta,
  PostCardTitle,
} from "@/components/portfolio/post-card"

const posts = [
  {
    slug: "tokens-are-an-api",
    title: "Tokens are an API",
    category: "Design systems",
    excerpt: "Semver, deprecation windows and codemods kept eleven product teams shipping.",
    date: "2025-12-09",
    readingTime: "11 min",
    art: "interface",
  },
  {
    slug: "color-in-oklch",
    title: "Rebuilding a palette in oklch()",
    category: "CSS",
    excerpt: "Perceptual color finally landed in CSS. Notes from rebuilding a palette with color-mix().",
    date: "2025-10-21",
    readingTime: "6 min",
    art: "bauhaus",
  },
  {
    slug: "shipping-small",
    title: "A year of shipping small",
    category: "Process",
    excerpt: "Twelve months of weekly releases, and what it did to the way the team plans and reviews.",
    date: "2025-08-04",
    readingTime: "5 min",
    art: "landscape",
  },
] as const

export default function PostCardMagazine() {
  return (
    <div className="mx-auto grid max-w-6xl gap-6 md:grid-cols-3">
      <PostCard variant="featured" href="#motion-with-intent" className="md:col-span-3">
        <PostCardMedia>
          <GenerativeArt seed="motion-with-intent" variant="landscape" />
        </PostCardMedia>
        <PostCardContent>
          <PostCardEyebrow>Featured</PostCardEyebrow>
          <PostCardTitle as="h2">Motion with intent</PostCardTitle>
          <PostCardExcerpt>
            Animation should answer a question the user just asked. A field guide to motion that informs instead of performs.
          </PostCardExcerpt>
          <PostCardMeta date="2026-02-18" readingTime="7 min" />
        </PostCardContent>
      </PostCard>
      {posts.map((post) => (
        <PostCard key={post.slug} href={`#${post.slug}`}>
          <PostCardMedia>
            <GenerativeArt seed={post.slug} variant={post.art} />
          </PostCardMedia>
          <PostCardContent>
            <PostCardEyebrow>{post.category}</PostCardEyebrow>
            <PostCardTitle>{post.title}</PostCardTitle>
            <PostCardExcerpt>{post.excerpt}</PostCardExcerpt>
            <PostCardMeta date={post.date} readingTime={post.readingTime} className="mt-auto pt-2" />
          </PostCardContent>
        </PostCard>
      ))}
    </div>
  )
}
```

## API Reference

### PostCard

An article card. `vertical` stacks the cover above the text, `horizontal` puts it beside the
text from `sm` up, and `featured` lays the text over a full-bleed cover. Compose it from the
parts below. Every part is optional except the title.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"vertical" \| "horizontal" \| "featured"` | `"vertical"` | `vertical`: cover on top, for grids. `horizontal`: cover beside the text from `sm` up, for lists. `featured`: text over a full-bleed cover, for the lead post. |
| `href` | `string` | — | Makes the whole card a link (via the title). External URLs open in a new tab and show ↗. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to the title link when `href` opens in a new tab. Translate it here. |

Also accepts every `article` prop.

### PostCardMedia

Cover slot. Put an `<img>`, `<Media>` or `<GenerativeArt>` inside; it zooms slightly on hover. The box keeps
its ratio before the image loads (16:10; in `horizontal` from `sm` up it fills the card's height, so a tall
image never stretches the card). Change the ratio with an `aspect-*` class.

Also accepts every `div` prop.

### PostCardContent

Text column: wraps the eyebrow, title, excerpt, meta and author.

Also accepts every `div` prop.

### PostCardEyebrow

Category label above the title, as plain text (the dot is decorative).

Also accepts every `p` prop.

### PostCardTitle

The post title. With `href` on the card it holds the link, stretched over the whole card. External links get a
visible ↗ (the arrow chip in `featured`) and the card's `newTabLabel` for screen readers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level. Use `h2` for a featured card that leads a page. |

Also accepts every `h3` prop.

### PostCardExcerpt

A sentence or two of summary, clamped to three lines.

Also accepts every `p` prop.

### PostCardMeta

Date · reading time. Extra children are appended with the same separator.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `date` | `Date \| string` | — | `Date` or ISO string, rendered in a `<time>` ("Feb 18, 2026"). |
| `readingTime` | `number \| React.ReactNode` | — | Minutes as a number (`7` → "7 min read") or text (`"7 min"` → "7 min read"; text that already ends in `readLabel` is shown as-is). |
| `readLabel` | `string` | `"read"` | Word after the reading time. Translate it here. |
| `locale` | `string` | `"en-US"` | Locale for the date and the minutes, e.g. `"de-DE"`. |

Also accepts every `div` prop.

### PostCardAuthor

Avatar (or initials) with the author's name and an optional second line. Sits at the bottom of the card.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Author name. Its initials are the avatar fallback. |
| `avatar` | `string` | — | Image URL. Falls back to initials. |
| `position` | `React.ReactNode` | — | Secondary line, e.g. the author's job title or position. |

Also accepts every `div` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Post List

> Writing index for blogs and notes: compact dated rows, an archive grouped by year with a sticky year label, or detailed entries with excerpt and tags.

Category: Content · Registry item: `@portfolio-kit/post-list` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/post-list) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/post-list.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/post-list
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/post-list.tsx` and the kit items it uses: `format`, `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  PostList,
  PostListItem,
} from "@/components/portfolio/post-list"

<PostList>
  <PostListItem href="/writing/design-systems" heading="Design systems are a way to make disagreements cheap" date="2025-09-02" readingTime={8} />
  <PostListItem href="/writing/tokens" heading="Tokens are an API" date="2025-06-18" readingTime={5} />
</PostList>
```

## Examples

### Demo

A compact writing index with date, title and reading time per row. An arrow slides in on hover.

```tsx
import { PostList, PostListItem } from "@/components/portfolio/post-list"

const posts = [
  { slug: "motion-with-intent", title: "Motion with intent", date: "2026-02-18", readingTime: "7 min", views: 12840 },
  { slug: "tokens-are-an-api", title: "Tokens are an API", date: "2025-12-09", readingTime: "11 min", views: 8210 },
  { slug: "boring-navigation", title: "The case for boring navigation", date: "2025-10-21", readingTime: "5 min", views: 21400 },
  { slug: "color-in-oklch", title: "Rebuilding a palette in oklch()", date: "2025-08-04", readingTime: "6 min", views: 5630 },
]

export default function PostListDemo() {
  return (
    <PostList className="mx-auto max-w-3xl">
      {posts.map((post) => (
        <PostListItem
          key={post.slug}
          href={`#${post.slug}`}
          heading={post.title}
          date={post.date}
          readingTime={post.readingTime}
          views={post.views}
        />
      ))}
    </PostList>
  )
}
```

### Grouped by Year

An archive grouped by year, with the year pinned while its posts scroll past. Tune the pin offset with `--post-list-sticky-top`.

```tsx
import { PostList, PostListItem } from "@/components/portfolio/post-list"

const posts = [
  { slug: "motion-with-intent", title: "Motion with intent", date: "2026-02-18", readingTime: "7 min" },
  { slug: "tokens-are-an-api", title: "Tokens are an API", date: "2025-12-09", readingTime: "11 min" },
  { slug: "boring-navigation", title: "The case for boring navigation", date: "2025-10-21", readingTime: "5 min" },
  { slug: "shipping-small", title: "A year of shipping small", date: "2025-03-14", readingTime: "6 min" },
  { slug: "subgrid", title: "Grids that bend without breaking", date: "2024-11-02", readingTime: "8 min" },
]

export default function PostListGrouped() {
  return (
    // Items must be direct children: the list reads each one's `date` to group them.
    <PostList variant="grouped" label="Archive" className="mx-auto max-w-3xl [--post-list-sticky-top:1.5rem]">
      {posts.map((post) => (
        <PostListItem key={post.slug} href={`#${post.slug}`} heading={post.title} date={post.date} readingTime={post.readingTime} />
      ))}
    </PostList>
  )
}
```

### Detailed

Excerpts and tags under each title, for a blog index where readers skim before they click. A post published elsewhere opens in a new tab and shows ↗.

```tsx
import { PostList, PostListItem } from "@/components/portfolio/post-list"

const posts = [
  {
    slug: "motion-with-intent",
    title: "Motion with intent",
    date: "2026-02-18",
    readingTime: "7 min",
    views: 12840,
    excerpt: "Animation should answer a question the user just asked. A field guide to motion that informs instead of performs.",
    tags: ["Motion", "UX"],
  },
  {
    slug: "tokens-are-an-api",
    title: "Tokens are an API",
    date: "2025-12-09",
    readingTime: "11 min",
    views: 8210,
    excerpt: "Treat tokens like a public API: semver, deprecation windows and codemods kept eleven product teams shipping.",
    tags: ["Design systems"],
  },
  {
    slug: "color-in-oklch",
    // A guest post on another site: absolute URLs open in a new tab.
    href: "https://example.com/rebuilding-a-palette-in-oklch",
    title: "Rebuilding a palette in oklch()",
    date: "2025-08-04",
    readingTime: "6 min",
    views: 5630,
    excerpt: "Perceptual color finally landed in CSS. Notes from rebuilding a palette with oklch() and color-mix().",
    tags: ["CSS", "Color"],
  },
]

export default function PostListDetailed() {
  return (
    <PostList variant="detailed" className="mx-auto max-w-2xl">
      {posts.map(({ slug, href = `#${slug}`, title, ...post }) => (
        <PostListItem key={slug} href={href} heading={title} {...post} />
      ))}
    </PostList>
  )
}
```

### In a Section

A “Writing” section for a home page: header with a link to the full archive, then the latest posts.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { PostList, PostListItem } from "@/components/portfolio/post-list"
import {
  Section,
  SectionContent,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const posts = [
  { slug: "motion-with-intent", title: "Motion with intent", date: "2026-02-18", readingTime: "7 min" },
  { slug: "tokens-are-an-api", title: "Tokens are an API", date: "2025-12-09", readingTime: "11 min" },
  { slug: "boring-navigation", title: "The case for boring navigation", date: "2025-10-21", readingTime: "5 min" },
]

export default function PostListInASection() {
  return (
    <Section id="writing" size="sm">
      <SectionHeader align="split">
        <div className="flex flex-col gap-4">
          <SectionEyebrow index={4}>Writing</SectionEyebrow>
          <SectionTitle>Notes on craft, systems and the web.</SectionTitle>
        </div>
        <ArrowLink href="#archive" className="shrink-0">
          All posts
        </ArrowLink>
      </SectionHeader>
      <SectionContent>
        <PostList label="Latest posts">
          {posts.map((post) => (
            <PostListItem key={post.slug} href={`#${post.slug}`} heading={post.title} date={post.date} readingTime={post.readingTime} />
          ))}
        </PostList>
      </SectionContent>
    </Section>
  )
}
```

## API Reference

### PostList

Wraps `PostListItem`s. In the `grouped` variant, items are grouped by the
year of their `date` prop (in the order given) under a sticky year heading
(offset with the `--post-list-sticky-top` CSS variable, default 5rem).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"rows" \| "grouped" \| "detailed"` | `"rows"` | `rows`: one compact line per post. `grouped`: an archive with a sticky year beside each group. `detailed`: entries with excerpt and tags. |
| `label` | `string` | `"Posts"` | Accessible name for the list. In `grouped`, each year's list is named "<label> <year>", e.g. "Posts 2025". |
| `headingLevel` | `2 \| 3 \| 4` | `3` | Heading level of the post titles, or of the year headings in `grouped` (posts are then one level below). Use `2` when the list sits directly under the page title, `4` under an `h3`. |
| `locale` | `string` | `"en-US"` | Locale for dates, minutes and view counts, e.g. `"de-DE"`. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to links that open in a new tab. Translate it here. |
| `readLabel` | `string` | `"read"` | Word after the reading time ("7 min read"; read out but not shown in `rows`). Translate it here. |
| `viewsLabel` | `string` | `"views"` | Word after the view count ("12.4K views"). Translate it here. |
| `tagsLabel` | `string` | `"Tags"` | Accessible name of each post's tag list (`detailed`). Translate it here. |
| `undatedLabel` | `string` | `"Undated"` | Year heading for posts without a valid `date` in `grouped`. Translate it here. |

Also accepts every `div` prop.

### PostListItem

One post. Renders as a dated row or a detailed entry depending on the parent `PostList` variant.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `React.ReactNode` | — | Post title (the row's heading). Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `href` | `string` | — | Link to the post. The whole row becomes clickable. External URLs open in a new tab and show ↗. |
| `date` | `Date \| string` | — | `Date` or ISO string, rendered in a `<time>`. Also decides the year group in the `grouped` variant. |
| `readingTime` | `number \| React.ReactNode` | — | Minutes as a number (`7` → "7 min") or text shown as written ("7 min"). The `detailed` variant appends "read". |
| `excerpt` | `React.ReactNode` | — | Summary under the title (`detailed` variant only). |
| `tags` | `string[]` | — | Topic chips under the excerpt (`detailed` variant only). |
| `views` | `number` | — | View count, shown compact ("12.4K views"): in the `detailed` variant, and in `rows` from `md` up. |
| `headingAs` | `"h2" \| "h3" \| "h4" \| "h5"` | — | Heading element for this item's title. Defaults to the list's `headingLevel` (one level lower when grouped). |
| `titleAs` | `"h2" \| "h3" \| "h4" \| "h5"` | — | Deprecated alias of `headingAs`. |

Also accepts every `li` prop.

## Used in templates

- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Preloader

> Intro screen with a 0–100 counter or cycling greetings, then a curtain lifts to reveal the page. Skippable with a click or any key, can show once per session, and skipped with reduced motion.

Category: Effects · Registry item: `@portfolio-kit/preloader` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/preloader) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/preloader.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/preloader
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/preloader.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { createPreloaderScript, Preloader, preloaderVariants } from "@/components/portfolio/preloader"
```

## Examples

### Demo

A 0→100 counter covers the page on first load, then the curtain lifts to reveal the hero. Click, tap or press any key to skip.

```tsx
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Preloader } from "@/components/portfolio/preloader"
import { typography } from "@/lib/typography"

const covers = ["lumen", "tidewater", "fieldnote"]

export default function PreloaderDemo() {
  return (
    <>
      <Preloader brand="Noa Vale" />
      <main className="flex min-h-svh flex-col justify-between gap-12 p-5 sm:p-8 md:p-10">
        <header className="flex items-center justify-between gap-4">
          <span className="font-heading text-base">Noa Vale</span>
          <span className={typography.eyebrow}>Portfolio ’25</span>
        </header>
        <div className="flex flex-col gap-6">
          <h1 className={cn(typography.display, "max-w-4xl")}>Design engineer building calm, fast interfaces.</h1>
          <ul role="list" className="grid grid-cols-3 gap-3">
            {covers.map((cover) => (
              <li key={cover} className="aspect-[4/3] overflow-hidden rounded-xl border">
                <GenerativeArt seed={cover} variant="interface" />
              </li>
            ))}
          </ul>
        </div>
      </main>
    </>
  )
}
```

### Greetings

The `words` variant flicks through “hello” in several languages on the accent color, each marked with its `lang`. A warmer intro for a personal site.

```tsx
import { cn } from "@/lib/utils"
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { Preloader } from "@/components/portfolio/preloader"
import { typography } from "@/lib/typography"

export default function PreloaderWords() {
  return (
    <>
      <Preloader
        variant="words"
        tone="highlight"
        brand="Noa Vale"
        label="Welcome"
        words={[
          { text: "Hello", lang: "en" },
          { text: "Olá", lang: "pt" },
          { text: "Bonjour", lang: "fr" },
          { text: "Ciao", lang: "it" },
          { text: "Hej", lang: "sv" },
          { text: "こんにちは", lang: "ja" }
        ]}
      />
      <main className="flex min-h-svh flex-col items-start justify-center gap-6 p-5 sm:p-8 md:p-16">
        <AvailabilityBadge />
        <h1 className={cn(typography.display, "max-w-4xl")}>Hi, I&rsquo;m Noa.</h1>
        <p className={cn(typography.lead, "max-w-md")}>
          I design and build calm, fast interfaces for ambitious product teams.
        </p>
      </main>
    </>
  )
}
```

### Real progress

Feed `progress` from your own loading (fonts, images, data) and the counter eases toward it, exiting at 100. Here it covers a single card with `position="absolute"`.

```tsx
import * as React from "react"

import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Preloader } from "@/components/portfolio/preloader"
import { typography } from "@/lib/typography"

/** Stand-in for real asset loading: quick bursts, then waits. */
function useFakeProgress() {
  const [progress, setProgress] = React.useState(0)
  React.useEffect(() => {
    const steps = [12, 34, 41, 63, 71, 88, 100]
    const timers = steps.map((value, i) => setTimeout(() => setProgress(value), 300 + i * 400))
    return () => timers.forEach(clearTimeout)
  }, [])
  return progress
}

export default function PreloaderRealProgress() {
  const progress = useFakeProgress()

  return (
    <div className="relative isolate mx-auto flex h-[30rem] max-w-3xl flex-col justify-end gap-3 overflow-hidden rounded-2xl border bg-card p-5 shadow-card md:p-8">
      <GenerativeArt seed="tidewater-field" variant="landscape" className="absolute inset-0 -z-10" />
      <div aria-hidden className="absolute inset-0 -z-10 bg-gradient-to-t from-card via-card/60 to-transparent" />
      <p className={typography.meta}>Case study · 24 images</p>
      <h2 className={cn(typography.title, "max-w-lg")}>Tidewater, in the field</h2>
      <Preloader position="absolute" tone="inverse" progress={progress} label="Loading gallery" brand="Tidewater" />
    </div>
  )
}
```

## API Reference

### Preloader

Covers the page (or its positioned parent) until the counter reaches 100 or the greetings run
out, then lifts away and unmounts. It's decoration, never a gate: a click, a tap or any key skips
it (with a visible skip button when it lasts over 2 s), `maxDuration` caps it, reduced motion
skips it entirely, and server-rendered HTML lifts it with CSS alone if JavaScript never runs.
With `once`, add `createPreloaderScript(storageKey)` to `<head>` on server-rendered pages.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"counter" \| "words"` | `"counter"` | `counter` counts 0→100 in big mono numerals; `words` flicks through greetings. |
| `position` | `"fixed" \| "absolute"` | `"fixed"` | `fixed` covers the viewport (page intro); `absolute` covers the nearest positioned parent (a card, a gallery). |
| `tone` | `"dark" \| "inverse" \| "default" \| "highlight"` | `"dark"` | Curtain color. `dark` uses the theme's dark palette in both modes, `inverse` a foreground-colored curtain, `default` the page surface and `highlight` the signature accent. |
| `duration` | `number` | `variant === "words" ? 2400 : 2600` | Total time before the curtain lifts, in ms (ignored while `progress` is controlled). |
| `progress` | `number` | — | Real loading progress, 0–100. The counter eases toward it and exits at 100. |
| `maxDuration` | `number` | `6000` | The longest the intro may cover the page, in ms. The curtain lifts then even if `progress` stalls below 100, so a slow or failed load never hides the content. |
| `onComplete` | `() => void` | — | Called once the page is revealed (or immediately when the preloader is skipped). |
| `once` | `boolean` | `false` | Show only once per browser session. On server-rendered pages, also add `createPreloaderScript(storageKey)` to `<head>` so the curtain doesn't flash for visitors who already saw it. If storage is blocked, the intro simply plays again. |
| `storageKey` | `string` | `"portfolio-kit:preloader"` | `sessionStorage` key used by `once` (and by `createPreloaderScript`). |
| `words` | `PreloaderWord[]` | `DEFAULT_WORDS` | Greetings for the `words` variant: strings, or `{ text, lang }` so each one is marked with its language. Defaults to "Hello" in eight languages. |
| `brand` | `React.ReactNode` | — | Small label in the top corner — your name or logo. |
| `label` | `string` | `"Loading"` | Status text shown in the corner and announced to assistive tech. |
| `loadedLabel` | `string` | `"Loaded"` | Announced to assistive tech as the curtain lifts. |
| `skipLabel` | `string` | `"Skip intro"` | Text of the skip button, shown when the intro can last longer than 2 s. |
| `lockScroll` | `boolean` | — | Lock page scroll while loading. Defaults to `true` when `position="fixed"`. |

Also accepts every `output` prop.

### type PreloaderWord

A greeting for the `words` variant. `lang` (a BCP 47 tag) picks the right font and pronunciation.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `text` (required) | `string` | — |  |
| `lang` | `string` | — |  |

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)



---

# Press List

> Press mentions with publication, headline, kind and date, as divided rows or a card grid. Each linked item is a single link.

Category: Social Proof · Registry item: `@portfolio-kit/press-list` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/press-list) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/press-list.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/press-list
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/press-list.tsx` and the kit items it uses: `format`, `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  PressItem,
  PressList,
} from "@/components/portfolio/press-list"

<PressList>
  <PressItem
    publication="The Interface"
    heading="The quiet craft of design engineering"
    date="2025-09-12"
    kind="Profile"
    href="https://example.com/profile"
  />
  <PressItem publication="Frontend Radio" heading="Motion that respects attention" date="2025-02-20" kind="Podcast" />
</PressList>
```

## Examples

### Demo

“Featured in” rows of publication, headline, kind and date, where each row links to the article.

```tsx
import { PressItem, PressList } from "@/components/portfolio/press-list"

/** Fictional publications and headlines. */
const press = [
  { publication: "The Interface", heading: "The quiet craft of design engineering", date: "2025-09-12", kind: "Profile" },
  { publication: "Pixel Weekly", heading: "How one designer shipped a system for eleven products", date: "2025-06-03", kind: "Case study" },
  { publication: "Frontend Radio", heading: "Episode 142 — Motion that respects attention", date: "2025-02-20", kind: "Podcast" },
  { publication: "Grid & Gutter", heading: "Ten portfolios that get the details right", date: "2024-11-08", kind: "Roundup" },
]

export default function PressListDemo() {
  return (
    <PressList className="mx-auto max-w-5xl">
      {press.map((item) => (
        <PressItem key={item.heading} {...item} href="https://example.com" />
      ))}
    </PressList>
  )
}
```

### Cards

The same mentions as a card grid with roomier headlines, for a dedicated press section.

```tsx
import { PressItem, PressList } from "@/components/portfolio/press-list"
import {
  Section,
  SectionContent,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const press = [
  { publication: "The Interface", heading: "The quiet craft of design engineering", date: "2025-09-12", kind: "Profile" },
  { publication: "Pixel Weekly", heading: "How one designer shipped a system for eleven products", date: "2025-06-03", kind: "Case study" },
  { publication: "Frontend Radio", heading: "Episode 142 — Motion that respects attention", date: "2025-02-20", kind: "Podcast" },
]

export default function PressListCards() {
  return (
    <Section>
      <SectionHeader>
        <SectionEyebrow>Featured in</SectionEyebrow>
        <SectionTitle>Press &amp; podcasts</SectionTitle>
      </SectionHeader>
      <SectionContent>
        <PressList variant="cards">
          {press.map((item) => (
            <PressItem key={item.heading} {...item} href="https://example.com" />
          ))}
        </PressList>
      </SectionContent>
    </Section>
  )
}
```

### Minimal

Publication, headline and date only, for mentions you can't link to.

```tsx
import { PressItem, PressList } from "@/components/portfolio/press-list"

const press = [
  { publication: "Studio Quarterly", heading: "The new wave of one-person studios", date: "2025-04-01" },
  { publication: "Design Annual", heading: "Twelve interfaces of the year", date: "2024-12-10" },
  { publication: "Grid & Gutter", heading: "Ten portfolios that get the details right", date: "2024-11-08" },
]

export default function PressListMinimal() {
  return (
    <PressList className="mx-auto max-w-3xl">
      {press.map((item) => (
        <PressItem key={item.heading} publication={item.publication} heading={item.heading} date={item.date} />
      ))}
    </PressList>
  )
}
```

## API Reference

### PressList

The `<ul>` of mentions, labelled "Press" (override with `aria-label`). `rows` for divided rows, `cards` for a card grid.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"rows" \| "cards"` | `"rows"` | `rows`: divided rows with the publication on the left, for a long list. `cards`: a grid of cards, for three to six highlights. |

Also accepts every `ul` prop.

### PressItem

One mention. Extra `children` render under the headline (a pull quote, a note).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `publication` (required) | `React.ReactNode` | — | Publication name, or a logo node (an SVG is sized to the label height; give it an accessible name). |
| `heading` | `React.ReactNode` | — | Headline or article title. Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `date` | `string` | — | ISO date (e.g. `"2025-06-18"`); shown as "Jun 2025" in a `<time>`. |
| `dateLabel` | `React.ReactNode` | — | Custom date text, e.g. "Forthcoming". Replaces the formatted `date` (which still sets `dateTime`). |
| `locale` | `string` | — | Locale used to format `date`. |
| `href` | `string` | — | Link to the article; the whole row or card becomes clickable. Absolute URLs open in a new tab. |
| `kind` | `React.ReactNode` | — | Optional kind, e.g. "Interview", "Podcast". |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the headline. Use `h4` when the list sits under an `h3`. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to links that open in a new tab. Translate it here. |

Also accepts every `li` prop.

## Used in templates

- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Pricing Table

> Two to four offers side by side (audit, sprint, retainer) with a featured tier, prices that switch with a billing toggle, aligned sections and a footnote.

Category: Services · Registry item: `@portfolio-kit/pricing-table` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/pricing-table) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/pricing-table.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/pricing-table
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/pricing-table.tsx` and the kit items it uses: `service-card`, `typography`, `view-toggle`.

## Usage

```tsx
import {
  ServiceCardAction,
  ServiceCardFeatures,
  ServiceCardHeader,
  ServiceCardTitle,
} from "@/components/portfolio/service-card"
import {
  PricingTable,
  PricingTableFootnote,
  PricingTableTiers,
  PricingTableToggle,
  PricingTier,
  PricingTierPrice,
} from "@/components/portfolio/pricing-table"

<PricingTable defaultBilling="project">
  <PricingTableToggle
    options={[
      { value: "project", label: "Per project" },
      { value: "monthly", label: "Monthly" },
    ]}
  />
  <PricingTableTiers columns={2}>
    <PricingTier>
      <ServiceCardHeader>
        <ServiceCardTitle>Sprint</ServiceCardTitle>
      </ServiceCardHeader>
      <PricingTierPrice currency="€" amount={{ project: 8000, monthly: 6800 }} />
      <ServiceCardFeatures features={["Kickoff workshop", "Two weeks of design & build"]} />
      <ServiceCardAction href="/contact">Book a sprint</ServiceCardAction>
    </PricingTier>
  </PricingTableTiers>
  <PricingTableFootnote>Prices exclude VAT.</PricingTableFootnote>
</PricingTable>
```

## Examples

### Demo

Three ways to work together, with the sprint featured. Switch between project and monthly billing and every price rolls over.

```tsx
import {
  PricingTable,
  PricingTableFootnote,
  PricingTableTiers,
  PricingTableToggle,
  PricingTier,
  PricingTierPrice,
} from "@/components/portfolio/pricing-table"
import {
  ServiceCardAction,
  ServiceCardDescription,
  ServiceCardFeatures,
  ServiceCardHeader,
  ServiceCardTitle,
} from "@/components/portfolio/service-card"

const tiers = [
  {
    name: "Audit",
    description: "A week-long review of your product's UX, accessibility and front-end quality.",
    amount: { project: 2400, monthly: 2400 },
    cadence: { project: "/audit", monthly: "one-off" },
    features: ["Heuristic & accessibility review", "Prioritised findings deck", "60-minute walkthrough call"],
    cta: "Book an audit",
  },
  {
    name: "Sprint",
    description: "Two focused weeks to design and ship one high-impact feature, end to end.",
    amount: { project: 9500, monthly: 8100 },
    cadence: { project: "/sprint", monthly: "/month" },
    note: { project: "Next opening: March", monthly: "Billed monthly, 3-month minimum" },
    features: ["Discovery workshop", "Interactive prototype", "Production-ready components", "Handover & docs"],
    cta: "Start a sprint",
    featured: true,
  },
  {
    name: "Retainer",
    description: "An embedded design engineer for teams who need steady, senior help.",
    amount: { project: "Let's talk", monthly: 6000 },
    prefix: { monthly: "from" },
    cadence: { monthly: "/month" },
    features: ["Two days a week", "Design system stewardship", "Async reviews within 24h"],
    cta: "Get in touch",
  },
]

export default function PricingTableDemo() {
  return (
    <PricingTable defaultBilling="project" className="mx-auto w-full max-w-6xl">
      <PricingTableToggle
        options={[
          { value: "project", label: "Per project" },
          { value: "monthly", label: "Monthly" },
        ]}
        note="Save 15% on monthly sprints"
      />
      <PricingTableTiers columns={3}>
        {tiers.map((tier) => (
          <PricingTier key={tier.name} featured={tier.featured}>
            <ServiceCardHeader>
              <ServiceCardTitle>{tier.name}</ServiceCardTitle>
              <ServiceCardDescription>{tier.description}</ServiceCardDescription>
            </ServiceCardHeader>
            <PricingTierPrice currency="€" amount={tier.amount} cadence={tier.cadence} prefix={tier.prefix} note={tier.note} />
            <ServiceCardFeatures features={tier.features} />
            <ServiceCardAction href="#contact">{tier.cta}</ServiceCardAction>
          </PricingTier>
        ))}
      </PricingTableTiers>
      <PricingTableFootnote>Prices exclude VAT. Half up front, half on delivery. Non-profits get 20% off.</PricingTableFootnote>
    </PricingTable>
  )
}
```

### Two tiers

No toggle, fixed prices: a simple “small project / full project” choice for a freelancer’s services page.

```tsx
import {
  PricingTable,
  PricingTableFootnote,
  PricingTableTiers,
  PricingTier,
  PricingTierPrice,
} from "@/components/portfolio/pricing-table"
import {
  ServiceCardAction,
  ServiceCardDescription,
  ServiceCardFeatures,
  ServiceCardHeader,
  ServiceCardTitle,
} from "@/components/portfolio/service-card"

export default function PricingTableTwoTiers() {
  return (
    <PricingTable className="mx-auto w-full max-w-4xl">
      <PricingTableTiers columns={2}>
        <PricingTier>
          <ServiceCardHeader>
            <ServiceCardTitle>Landing page</ServiceCardTitle>
            <ServiceCardDescription>One page, designed and built in two weeks.</ServiceCardDescription>
          </ServiceCardHeader>
          <PricingTierPrice currency="$" amount={3200} cadence="/project" />
          <ServiceCardFeatures features={["Copy review", "Responsive design & build", "Two rounds of revisions"]} />
          <ServiceCardAction href="#contact">Get a landing page</ServiceCardAction>
        </PricingTier>
        <PricingTier featured badge="Best value">
          <ServiceCardHeader>
            <ServiceCardTitle>Full site</ServiceCardTitle>
            <ServiceCardDescription>Brand-to-launch website for a small studio or product, with a CMS your team can use.</ServiceCardDescription>
          </ServiceCardHeader>
          <PricingTierPrice currency="$" amount={12000} prefix="from" cadence="/project" note="Typical timeline: 6–8 weeks" />
          <ServiceCardFeatures
            features={["Up to 8 page templates", "CMS setup & training", "Performance & SEO pass", "30 days of support"]}
          />
          <ServiceCardAction href="#contact">Plan a full site</ServiceCardAction>
        </PricingTier>
      </PricingTableTiers>
      <PricingTableFootnote>Every project starts with a free 30-minute call.</PricingTableFootnote>
    </PricingTable>
  )
}
```

### Studio plans

Four subscription tiers for a small design studio, billed monthly or yearly: two per row on tablets, four on desktop.

```tsx
import {
  PricingTable,
  PricingTableFootnote,
  PricingTableTiers,
  PricingTableToggle,
  PricingTier,
  PricingTierPrice,
} from "@/components/portfolio/pricing-table"
import {
  ServiceCardAction,
  ServiceCardDescription,
  ServiceCardFeatures,
  ServiceCardHeader,
  ServiceCardTitle,
} from "@/components/portfolio/service-card"

const plans = [
  {
    name: "Pause",
    description: "Keep your slot while things are quiet.",
    amount: { monthly: 290, yearly: 240 },
    features: ["Priority when you resume", "Quarterly check-in"],
    cta: "Hold my slot",
  },
  {
    name: "Studio",
    description: "One request at a time, delivered in days.",
    amount: { monthly: 4200, yearly: 3500 },
    features: ["Unlimited requests, one active", "48h average turnaround", "Figma + code handoff"],
    cta: "Start Studio",
  },
  {
    name: "Studio Pro",
    description: "Two requests in flight and a weekly call.",
    amount: { monthly: 6900, yearly: 5750 },
    features: ["Two active requests", "Weekly review call", "Design system upkeep", "Slack channel"],
    cta: "Start Studio Pro",
    featured: true,
  },
  {
    name: "Embedded",
    description: "A designer inside your team, three days a week.",
    amount: { monthly: "Custom", yearly: "Custom" },
    features: ["Joins your rituals", "Hiring & mentoring help"],
    note: "Scoped per team",
    cta: "Talk to us",
  },
]

export default function PricingTableStudioPlans() {
  return (
    <PricingTable defaultBilling="monthly" className="mx-auto w-full max-w-7xl">
      <PricingTableToggle
        options={[
          { value: "monthly", label: "Monthly" },
          { value: "yearly", label: "Yearly" },
        ]}
        note="Two months free, billed yearly"
      />
      <PricingTableTiers columns={4}>
        {plans.map((plan) => (
          <PricingTier key={plan.name} featured={plan.featured} badge="Most teams">
            <ServiceCardHeader>
              <ServiceCardTitle>{plan.name}</ServiceCardTitle>
              <ServiceCardDescription>{plan.description}</ServiceCardDescription>
            </ServiceCardHeader>
            <PricingTierPrice
              currency="$"
              amount={plan.amount}
              cadence={typeof plan.amount.monthly === "number" ? "/month" : undefined}
              note={plan.note ?? { monthly: "Cancel any time", yearly: "Billed once a year" }}
            />
            <ServiceCardFeatures features={plan.features} />
            <ServiceCardAction href="#start">{plan.cta}</ServiceCardAction>
          </PricingTier>
        ))}
      </PricingTableTiers>
      <PricingTableFootnote>Prices per month, excluding tax. Switch or pause plans at the end of any billing period.</PricingTableFootnote>
    </PricingTable>
  )
}
```

## API Reference

### PricingTable

Root. Holds the billing option shared by the toggle and every price. Put an optional
`<PricingTableToggle>`, then `<PricingTableTiers>` and an optional `<PricingTableFootnote>` inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `billing` | `string` | — | Selected billing option (controlled), e.g. `"project"` or `"monthly"`. |
| `defaultBilling` | `string` | `""` | Initially selected billing option (uncontrolled). |
| `onBillingChange` | `(billing: string) => void` | — | Called when the visitor switches billing. |

Also accepts every `div` prop.

### PricingTableToggle

Segmented control (a radio group: arrow keys move and select) that switches every
`<PricingTierPrice>` between billing options. After a switch, screen readers hear one polite
"Prices updated: Monthly" instead of every price at once.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `{ value: string; label: string }[]` | — | The billing options, e.g. `[{ value: "project", label: "Per project" }, { value: "monthly", label: "Monthly" }]`. |
| `note` | `React.ReactNode` | — | Small text next to the toggle, e.g. "Save 15% with a retainer". |
| `label` | `string` | `"Billing"` | Accessible name of the toggle. |
| `updatedLabel` | `string` | `"Prices updated: {option}"` | Announced to screen readers after the visitor switches; `{option}` becomes the option's label. |

Also accepts every `div` prop.

### PricingTableTiers

The row of tiers, a list (`<ul>`), so screen readers announce how many offers there are. Side by
side (from `md` for two tiers, `lg` for more), each tier's header, price, features and action sit on
shared rows (CSS subgrid), so prices and buttons line up however long each tier's text is. On phones
the tiers stack in source order; the featured one keeps its badge.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `2 \| 3 \| 4` | `3` | Tiers per row (2 from `md` up, 3–4 from `lg` up). Match your number of tiers. |

Also accepts every `ul` prop.

### PricingTier

One tier: a list item holding a `ServiceCard` (`className` and other props go to the card) on the
table's shared rows. Give it exactly four children, in order: `ServiceCardHeader`,
`PricingTierPrice`, `ServiceCardFeatures` and `ServiceCardAction`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `featured` | `boolean` | — | Highlight this offer: accent border, tinted background, a badge on the top edge, filled checks and a solid button. |
| `badge` | `React.ReactNode \| false` | — | Badge on the top edge when featured. It's the only part screen readers hear as "featured", so keep it (or say so in the title) when you can. Pass `false` to hide. |

Also accepts every `ServiceCard` prop.

### PricingTierPrice

The tier's price. Values can differ per billing option; when the visitor switches, the new price
rolls in (instantly under reduced motion). Text amounts ("Let's talk") drop the currency symbol.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `amount` (required) | `PerBilling<number \| string>` | — | The price, or one per billing option: `{ project: 4800, monthly: 1600 }`. Numbers get thousands separators. |
| `currency` | `string` | — | Symbol placed before the amount, e.g. "€". |
| `locale` | `string` | — | Locale used to format numeric amounts, e.g. `"de-DE"` → "8.000". |
| `cadence` | `PerBilling<React.ReactNode>` | — | After the amount, e.g. "/project", or one per billing option: `{ project: "/project", monthly: "/month" }`. |
| `prefix` | `PerBilling<React.ReactNode>` | — | Before the amount, e.g. "from" (or one per billing option). |
| `note` | `PerBilling<React.ReactNode>` | — | Small print under the price (or one per billing option). |

Also accepts every `ServiceCardPrice` prop.

### PricingTableFootnote

Small print under the tiers: payment terms, VAT, "custom scopes welcome".

Also accepts every `p` prop.



---

# Principles

> Numbered values or process steps (01, 02, 03…) as a card grid or divided rows with large numbers.

Category: About · Registry item: `@portfolio-kit/principles` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/principles) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/principles.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/principles
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/principles.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  Principle,
  Principles,
} from "@/components/portfolio/principles"

<Principles>
  <Principle heading="Start with the words">
    Content before chrome. If the copy is unclear, no layout will save it.
  </Principle>
  <Principle heading="Prototype in the real medium">Browsers, not pictures of browsers.</Principle>
  <Principle heading="Make it calm">Fewer colours, fewer weights, fewer surprises.</Principle>
</Principles>
```

## Examples

### Demo

Numbered values as cards, to show how you think as well as what you've made.

```tsx
import { Principle, Principles } from "@/components/portfolio/principles"

export default function PrinciplesDemo() {
  return (
    <Principles className="mx-auto w-full max-w-5xl">
      <Principle heading="Start with the words">
        Content before chrome. If the copy is unclear, no layout will save it — so we write first and design around it.
      </Principle>
      <Principle heading="Prototype in the real medium">
        Browsers, not pictures of browsers. Motion, latency and edge cases only show up in code.
      </Principle>
      <Principle heading="Make it calm">
        Fewer colours, fewer weights, fewer surprises. Delight is earned by getting out of the way.
      </Principle>
    </Principles>
  )
}
```

### List

Large numbers and divided rows for a slower read, such as a manifesto or “how I work” page.

```tsx
import { Principle, Principles } from "@/components/portfolio/principles"

export default function PrinciplesList() {
  return (
    <Principles variant="list" className="mx-auto w-full max-w-3xl">
      <Principle heading="Accessible by default">
        Keyboard, contrast and reduced motion are part of the first pass, never a ticket for later.
      </Principle>
      <Principle heading="Ship, then sand">
        Put it in front of people early, then polish the parts they actually touch.
      </Principle>
      <Principle heading="Leave it better">
        Every project should leave the team with sharper tools and a clearer system than before.
      </Principle>
    </Principles>
  )
}
```

### Process

Override the number with `index` to label process phases with letters, week numbers or other short labels.

```tsx
import { Principle, Principles } from "@/components/portfolio/principles"

const steps = [
  {
    index: "Wk 1",
    title: "Discover",
    description: "Interviews, an audit of what exists and a one-page brief we both sign off on.",
  },
  {
    index: "Wk 2–4",
    title: "Design & prototype",
    description: "Working prototypes in the browser, reviewed twice a week with real content.",
  },
  {
    index: "Wk 5+",
    title: "Build & hand over",
    description: "Production code, documentation and a recorded walkthrough for your team.",
  },
]

export default function PrinciplesProcess() {
  return (
    <Principles className="mx-auto w-full max-w-5xl">
      {steps.map((step) => (
        <Principle key={step.title} index={step.index} heading={step.title}>
          {step.description}
        </Principle>
      ))}
    </Principles>
  )
}
```

### In a Section

A split section header over two columns of numbered rows: a complete “How I work” block for an about page.

```tsx
import { Principle, Principles } from "@/components/portfolio/principles"
import {
  Section,
  SectionContent,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

export default function PrinciplesInASection() {
  return (
    <Section spacing="sm">
      <SectionHeader align="split">
        <div className="flex flex-col gap-4">
          <SectionEyebrow index={5}>How I work</SectionEyebrow>
          <SectionTitle>Principles I keep coming back to</SectionTitle>
        </div>
        <SectionDescription className="md:max-w-sm">
          Not rules — defaults. They bend when a project asks them to.
        </SectionDescription>
      </SectionHeader>
      <SectionContent>
        <Principles variant="list" columns={2}>
          <Principle heading="Start with the words">
            Content before chrome. We write first and design around it.
          </Principle>
          <Principle heading="Prototype in the real medium">
            Motion, latency and edge cases only show up in code.
          </Principle>
          <Principle heading="Accessible by default">
            Keyboard, contrast and reduced motion are part of the first pass.
          </Principle>
          <Principle heading="Ship, then sand">
            Put it in front of people early, then polish what they touch.
          </Principle>
        </Principles>
      </SectionContent>
    </Section>
  )
}
```

## API Reference

### Principles

An ordered list (`<ol>`) of principles or steps. Screen readers announce each item's position
from the list itself; the visible numbers are drawn with a CSS counter and hidden from them, so
nothing is read twice. `start` (e.g. `start={4}` to continue a list) moves both.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"cards" \| "list" \| null` | `"cards"` | `cards`: a grid of numbered cards. `list`: divided rows with large numbers. |
| `columns` | `1 \| 2 \| 3 \| null` | `3` | Columns from `md` up. Defaults to 3 for cards and 1 for the list. |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of each principle, so the list fits your page outline (`h4` under an `h3`). |

Also accepts every `ol` prop.

### Principle

One principle: its number, a heading and a short explanation (the children).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `React.ReactNode` | — | The principle itself, short. Rendered as a heading (`headingLevel` on `Principles`, default `h3`). Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `index` | `string \| number` | — | Replace the automatic number with a label, e.g. `"A"`, `"Wk 1"` or `7` (→ "07"). Unlike the automatic number, a custom label is content, so screen readers hear it before the heading. |

Also accepts every `li` prop.



---

# Process Steps

> How-I-work timeline of numbered steps with heading, description and duration, joined by a line. Stacks on mobile, runs in a row on large screens, and can mark a current step.

Category: Services · Registry item: `@portfolio-kit/process-steps` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/process-steps) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/process-steps.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/process-steps
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/process-steps.tsx` and the kit items it uses: `typography`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import {
  ProcessStep,
  ProcessSteps,
} from "@/components/portfolio/process-steps"

<ProcessSteps>
  <ProcessStep heading="Discover" duration="Week 1" description="A kickoff workshop to align on goals and constraints." />
  <ProcessStep heading="Design" duration="Weeks 2–4" description="Prototypes in code, reviewed every Friday." />
  <ProcessStep heading="Ship" duration="Week 5" description="Launch, handover docs and a month of support." />
</ProcessSteps>
```

## Examples

### Demo

Show how a project runs, start to finish. Stacked on phones, a connected row on large screens.

```tsx
import { ProcessStep, ProcessSteps } from "@/components/portfolio/process-steps"
import {
  Section,
  SectionContent,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const steps = [
  {
    title: "Discover",
    duration: "Week 1",
    description: "A kickoff workshop to align on goals, constraints and what success looks like.",
  },
  {
    title: "Design",
    duration: "Weeks 2–4",
    description: "Flows, prototypes and a visual direction, reviewed together every Friday.",
  },
  {
    title: "Build",
    duration: "Weeks 4–8",
    description: "Production code in small, reviewable pull requests with a live staging link.",
  },
  {
    title: "Launch & learn",
    duration: "Week 9",
    description: "Ship, measure and hand over docs so your team owns it from day one.",
  },
]

export default function ProcessStepsDemo() {
  return (
    <Section>
      <SectionHeader>
        <SectionEyebrow index={4}>Process</SectionEyebrow>
        <SectionTitle>How a project runs</SectionTitle>
      </SectionHeader>
      <SectionContent>
        <ProcessSteps>
          {steps.map((step) => (
            <ProcessStep key={step.title} heading={step.title} duration={step.duration} description={step.description} />
          ))}
        </ProcessSteps>
      </SectionContent>
    </Section>
  )
}
```

### Project Tracker

Pass `active` to turn the steps into a status tracker: earlier steps are checked off and the current one is highlighted.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { ProcessStep, ProcessSteps } from "@/components/portfolio/process-steps"
import { typography } from "@/lib/typography"

const steps = [
  { title: "Kickoff", duration: "Oct 6" },
  { title: "Design review", duration: "Oct 17" },
  {
    title: "Build",
    duration: "In progress · Oct 20 – Nov 14",
    description: "Checkout and account pages are live on staging.",
  },
  { title: "Launch", duration: "Nov 18" },
]

export default function ProcessStepsTracker() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-6 rounded-2xl border bg-card p-5 text-card-foreground shadow-card md:p-6">
      <div className="flex items-baseline justify-between gap-4">
        <h2 className={typography.heading}>Kiln storefront</h2>
        <p className={typography.meta}>3 of 4</p>
      </div>
      <ProcessSteps orientation="vertical" active={2} className="[&>li]:pb-7">
        {steps.map((step) => (
          <ProcessStep key={step.title} heading={step.title} duration={step.duration} description={step.description} />
        ))}
      </ProcessSteps>
      <div className="border-t pt-5">
        <ArrowLink href="#staging" className="text-sm">
          Open staging
        </ArrowLink>
      </div>
    </div>
  )
}
```

### Split

A vertical timeline beside a pinned heading, for services pages where each step needs more room.

```tsx
import { ProcessStep, ProcessSteps } from "@/components/portfolio/process-steps"
import {
  Section,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const steps = [
  {
    title: "Intro call",
    duration: "30 minutes · free",
    description: "We talk through goals, timeline and budget. If we're not a fit, I'll point you to someone who is.",
  },
  {
    title: "Proposal",
    duration: "Within 3 days",
    description: "A fixed-price scope with milestones, deliverables and a start date — no hourly surprises.",
  },
  {
    title: "Sprints",
    duration: "2-week cycles",
    description: "Design and code ship together. You get a Friday demo and a staging link that's always up to date.",
  },
  {
    title: "Handover",
    duration: "Final week",
    description: "Docs, a recorded walkthrough and 30 days of support so your team owns it with confidence.",
  },
]

export default function ProcessStepsSplit() {
  return (
    <Section>
      <div className="grid gap-12 md:grid-cols-[1fr_1.3fr] md:gap-16 lg:gap-24">
        <SectionHeader className="md:sticky md:top-24 md:self-start">
          <SectionEyebrow>How we&apos;ll work</SectionEyebrow>
          <SectionTitle>Four steps, no surprises</SectionTitle>
          <SectionDescription>Every engagement follows the same rhythm, whether it lasts two weeks or six months.</SectionDescription>
        </SectionHeader>
        <ProcessSteps orientation="vertical">
          {steps.map((step) => (
            <ProcessStep key={step.title} heading={step.title} duration={step.duration} description={step.description} />
          ))}
        </ProcessSteps>
      </div>
    </Section>
  )
}
```

## API Reference

### ProcessSteps

The ordered list (`<ol>`) of `ProcessStep`s. They must be direct children, so each knows its
number. Screen readers take the position from the list; the visible numbers are hidden from them,
so nothing is read twice. `start` (e.g. `start={4}` to continue a list) moves both.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"responsive" \| "vertical" \| "horizontal"` | `"responsive"` | `responsive` stacks on mobile and lays steps out in a row from `lg`. |
| `active` | `number` | — | Zero-based index of the current step. Earlier steps show as complete. |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of every step, so the list fits your page outline (`h4` under an `h3`). A step's own `headingLevel` wins. |
| `completeLabel` | `string` | `"Completed"` | Screen-reader prefix for completed steps when `active` is set ("Completed: Kickoff"). |
| `currentLabel` | `string` | `"Current step"` | Screen-reader prefix for the current step when `active` is set ("Current step: Build"). |

Also accepts every `ol` prop.

### ProcessStep

One step. Numbered automatically; extra `children` render under the description.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `React.ReactNode` | — | Step name, e.g. "Discover". Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `description` | `React.ReactNode` | — | One or two sentences on what happens in this step. |
| `duration` | `React.ReactNode` | — | Timing shown above the title, e.g. "Week 1–2" or a date. |
| `marker` | `React.ReactNode` | — | Override the marker content (defaults to the step number, or a check when complete). |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | — | Heading level of this step. Defaults to the list's `headingLevel` (`h3`). |

Also accepts every `li` prop.

## Used in templates

- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)



---

# Product Card

> Shop card for courses, prints and templates: cover, badge, details, price with a compare-at discount and a call to action. The whole card is one link.

Category: Content · Registry item: `@portfolio-kit/product-card` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/product-card) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/product-card.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/product-card
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/product-card.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

shadcn/ui primitives: `button`.

## Usage

```tsx
import {
  ProductCard,
  ProductCardAction,
  ProductCardBadge,
  ProductCardContent,
  ProductCardDescription,
  ProductCardFooter,
  ProductCardMedia,
  ProductCardPrice,
  ProductCardTitle,
} from "@/components/portfolio/product-card"

<ProductCard href="/shop/motion-for-interfaces">
  <ProductCardMedia>
    <img src="/motion-course.jpg" alt="" />
    <ProductCardBadge tone="highlight">Bestseller</ProductCardBadge>
  </ProductCardMedia>
  <ProductCardContent>
    <ProductCardTitle>Motion for Interfaces</ProductCardTitle>
    <ProductCardDescription>Purposeful UI animation, from easing to reduced motion.</ProductCardDescription>
    <ProductCardFooter>
      <ProductCardPrice price={79} />
      <ProductCardAction href="/shop/motion-for-interfaces/buy">Buy</ProductCardAction>
    </ProductCardFooter>
  </ProductCardContent>
</ProductCard>
```

## Examples

### Demo

A course card with a badge, details, a sale price and a call to action that stays clickable inside the card link.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProductCard,
  ProductCardAction,
  ProductCardBadge,
  ProductCardContent,
  ProductCardDescription,
  ProductCardFooter,
  ProductCardMedia,
  ProductCardMeta,
  ProductCardPrice,
  ProductCardTitle,
} from "@/components/portfolio/product-card"

export default function ProductCardDemo() {
  return (
    <ProductCard href="#motion-for-interfaces" className="w-full max-w-sm">
      <ProductCardMedia>
        <GenerativeArt seed="motion-course" variant="interface" />
        <ProductCardBadge tone="highlight">Bestseller</ProductCardBadge>
      </ProductCardMedia>
      <ProductCardContent>
        <ProductCardMeta>
          <span>Video course</span>
          <span>12 lessons</span>
          <span>3h 20m</span>
        </ProductCardMeta>
        <ProductCardTitle>Motion for Interfaces</ProductCardTitle>
        <ProductCardDescription>
          Purposeful UI animation — easing, choreography and reduced motion done right.
        </ProductCardDescription>
        <ProductCardFooter>
          <ProductCardPrice price={79} compareAt={129} />
          <ProductCardAction href="#enroll" size="sm">
            Enroll
          </ProductCardAction>
        </ProductCardFooter>
      </ProductCardContent>
    </ProductCard>
  )
}
```

### Minimal

No card border or padding, just the artwork with text below. Suits print shops and photography; this one links to an external store, so the title shows ↗.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProductCard,
  ProductCardBadge,
  ProductCardContent,
  ProductCardMedia,
  ProductCardMeta,
  ProductCardPrice,
  ProductCardTitle,
} from "@/components/portfolio/product-card"

export default function ProductCardMinimal() {
  return (
    <ProductCard variant="minimal" href="https://prints.example.com/tagus-at-dusk" className="w-80 max-w-full">
      <ProductCardMedia className="aspect-[4/5]">
        <GenerativeArt seed="tagus-at-dusk" variant="landscape" />
        <ProductCardBadge>12 left</ProductCardBadge>
      </ProductCardMedia>
      <ProductCardContent>
        <ProductCardMeta>
          <span>Giclée print</span>
          <span>A3</span>
        </ProductCardMeta>
        <ProductCardTitle className="text-base md:text-lg">Tagus at Dusk</ProductCardTitle>
        <ProductCardPrice price={120} />
      </ProductCardContent>
    </ProductCard>
  )
}
```

### Shop

A responsive shop grid (a list of products) mixing discounted, new and free products; the free one downloads from an external store. Footers line up because every card fills its row.

```tsx
import type * as React from "react"

import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProductCard,
  ProductCardAction,
  ProductCardBadge,
  ProductCardContent,
  ProductCardDescription,
  ProductCardFooter,
  ProductCardMedia,
  ProductCardMeta,
  ProductCardPrice,
  ProductCardTitle,
} from "@/components/portfolio/product-card"

type Product = {
  slug: string
  name: string
  description: string
  meta: string[]
  price: number
  compareAt?: number
  badge?: { label: string; tone: "default" | "highlight" }
  cta: string
  /** Checkout or download link; defaults to an on-site checkout. */
  ctaHref?: string
  art: React.ComponentProps<typeof GenerativeArt>["variant"]
}

const products: Product[] = [
  {
    slug: "motion-for-interfaces",
    name: "Motion for Interfaces",
    description: "A video course on purposeful UI animation: easing, choreography and timing.",
    meta: ["Course", "12 lessons"],
    price: 79,
    compareAt: 129,
    badge: { label: "Bestseller", tone: "highlight" },
    cta: "Enroll",
    art: "interface",
  },
  {
    slug: "design-tokens-starter",
    name: "Design Tokens Starter",
    description: "Figma variables and a typed token pipeline you can drop into any React project.",
    meta: ["Template", "v2.1"],
    price: 49,
    badge: { label: "New", tone: "default" },
    cta: "Get the kit",
    art: "interface",
  },
  {
    slug: "portfolio-field-guide",
    name: "The Portfolio Field Guide",
    description: "A 40-page PDF on writing case studies that hiring managers actually finish.",
    meta: ["Ebook", "40 pages"],
    price: 0,
    cta: "Download",
    ctaHref: "https://store.example.com/portfolio-field-guide",
    art: "bauhaus",
  },
]

export default function ProductCardShop() {
  return (
    <ul role="list" className="mx-auto grid max-w-6xl gap-6 sm:grid-cols-2 lg:grid-cols-3">
      {products.map((product) => (
        <li key={product.slug} className="flex">
          <ProductCard href={`#${product.slug}`} className="flex-1">
            <ProductCardMedia>
              <GenerativeArt seed={product.slug} variant={product.art} />
              {product.badge && <ProductCardBadge tone={product.badge.tone}>{product.badge.label}</ProductCardBadge>}
            </ProductCardMedia>
            <ProductCardContent>
              <ProductCardMeta>
                {product.meta.map((item) => (
                  <span key={item}>{item}</span>
                ))}
              </ProductCardMeta>
              <ProductCardTitle>{product.name}</ProductCardTitle>
              <ProductCardDescription>{product.description}</ProductCardDescription>
              <ProductCardFooter>
                <ProductCardPrice price={product.price} compareAt={product.compareAt} />
                <ProductCardAction
                  href={product.ctaHref ?? `#buy-${product.slug}`}
                  size="sm"
                  variant={product.price === 0 ? "outline" : "default"}
                >
                  {product.cta}
                </ProductCardAction>
              </ProductCardFooter>
            </ProductCardContent>
          </ProductCard>
        </li>
      ))}
    </ul>
  )
}
```

## API Reference

### ProductCard

A product in a shop grid. `card` is a bordered card; `minimal` drops the chrome and lets the
artwork carry it (prints, photography). With `href`, the whole card links to the product page
while a `ProductCardAction` inside stays independently clickable (e.g. straight to checkout).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"card" \| "minimal"` | `"card"` | `card`: bordered card with padding. `minimal`: no border or background, for a gallery-like shop grid. |
| `href` | `string` | — | Product page. Makes the whole card a link (via the title). External URLs open in a new tab and show ↗. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added to external links (the title and `ProductCardAction`). Translate it here. |

Also accepts every `article` prop.

### ProductCardMedia

Cover slot for an `<img>`, `<Media>` or `<GenerativeArt>`. Place a `ProductCardBadge` inside to pin it to the corner.

Also accepts every `div` prop.

### ProductCardBadge

A short label pinned to the top-left of the media ("New", "Bestseller", "12 left"). `tone="highlight"`
fills it with the theme's accent; use it on one card per row at most.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"default" \| "highlight"` | `"default"` | `default`: a neutral frosted pill. `highlight`: the theme accent, for the one item you want noticed. |

Also accepts every `span` prop.

### ProductCardContent

Text column: meta, title, description and footer.

Also accepts every `div` prop.

### ProductCardMeta

Small details, e.g. "12 lessons · 3h". Children are separated with a dot.

Also accepts every `div` prop.

### ProductCardTitle

Product name. With `href` on the card it holds the card's only link, stretched over the whole
card (the link's name is just the title). An external `href` adds ↗ and the new-tab hint.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level, to fit the page outline (e.g. `h2` when the shop grid has no section heading). |

Also accepts every `h3` prop.

### ProductCardDescription

One or two lines about the product, clamped to two (the product page has the rest).

Also accepts every `p` prop.

### ProductCardFooter

Bottom row, pushed to the card's end so footers line up across a grid: price on the left, action on the right.

Also accepts every `div` prop.

### ProductCardPrice

The price, with an optional struck-through compare-at price and the percentage saved. A sale is
announced as one phrase ("Was $129, now $79") rather than two bare numbers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `price` (required) | `number \| string` | — | Number (formatted with `currency` and `locale`) or a preformatted string. `0` renders `freeLabel`. |
| `compareAt` | `number \| string` | — | Original price, shown struck through. Ignored when both are numbers and it isn't higher than `price`. |
| `currency` | `string` | `"USD"` | ISO 4217 code used to format numeric prices. |
| `locale` | `string` | `"en-US"` | Locale used to format numeric prices and the percentage saved. |
| `showSavings` | `boolean` | `true` | Show "Save 38%" when both prices are numbers. |
| `freeLabel` | `string` | `"Free"` | Text for a price of `0`. |
| `saleLabel` | `string` | `"Was {compareAt}, now {price}"` | What screen readers hear for a discounted price, instead of the two numbers. `{compareAt}` and `{price}` are replaced with the formatted prices, so translations can reorder them. |
| `savingsLabel` | `string` | `"Save {percent}"` | Savings text; `{percent}` is replaced with the percentage formatted for `locale` (e.g. "38%"). |

Also accepts every `p` prop.

### ProductCardAction

Call to action (e.g. "Buy now"). A separate link, never nested in the title link: it sits above the
card's stretched link so it stays independently clickable. External URLs open in a new tab and show ↗.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `newTabLabel` | `string` | — | Screen-reader text for an external `href`. Defaults to the card's `newTabLabel`. |

Also accepts every `a` prop.



---

# Profile Card

> Link-in-bio style card with avatar, name, role, location, status, bio, socials and a primary action. Vertical card or compact row.

Category: Hero · Registry item: `@portfolio-kit/profile-card` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/profile-card) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/profile-card.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/profile-card
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/profile-card.tsx` and the kit items it uses: `generative-art`, `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

shadcn/ui primitives: `button`.

## Usage

```tsx
import {
  ProfileCard,
  ProfileCardAction,
  ProfileCardAvatar,
  ProfileCardBio,
  ProfileCardContent,
  ProfileCardFooter,
  ProfileCardLocation,
  ProfileCardName,
  ProfileCardRole,
} from "@/components/portfolio/profile-card"

<ProfileCard>
  <ProfileCardAvatar src="/avatar.jpg" alt="Noa Vale" initials="NV" />
  <ProfileCardContent>
    <ProfileCardName>Noa Vale</ProfileCardName>
    <ProfileCardRole>Design Engineer</ProfileCardRole>
    <ProfileCardLocation>Lisbon, Portugal</ProfileCardLocation>
  </ProfileCardContent>
  <ProfileCardBio>I design and build calm, fast interfaces.</ProfileCardBio>
  <ProfileCardFooter>
    <ProfileCardAction href="mailto:hello@example.com">Get in touch</ProfileCardAction>
  </ProfileCardFooter>
</ProfileCard>
```

## Examples

### Demo

A link-in-bio card: avatar, name, role, location, status, a one-line bio, socials and one clear call to action.

```tsx
import { Mail } from "lucide-react"

import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProfileCard,
  ProfileCardAction,
  ProfileCardAvatar,
  ProfileCardBio,
  ProfileCardContent,
  ProfileCardFooter,
  ProfileCardLocation,
  ProfileCardName,
  ProfileCardRole,
  ProfileCardStatus,
} from "@/components/portfolio/profile-card"
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"

const socials = [
  "https://github.com/example",
  "https://x.com/example",
  "https://www.linkedin.com/in/example",
  "https://dribbble.com/example",
]

export default function ProfileCardDemo() {
  return (
    <ProfileCard className="w-full max-w-sm">
      <ProfileCardAvatar>
        <GenerativeArt seed="Noa Vale" variant="portrait" grain={false} />
      </ProfileCardAvatar>
      <ProfileCardContent>
        <ProfileCardName>Noa Vale</ProfileCardName>
        <ProfileCardRole>Design Engineer</ProfileCardRole>
        <ProfileCardLocation>Lisbon, Portugal</ProfileCardLocation>
      </ProfileCardContent>
      <ProfileCardStatus>
        <AvailabilityBadge variant="soft" detail="from Nov">
          Available
        </AvailabilityBadge>
      </ProfileCardStatus>
      <ProfileCardBio>I design and build calm, fast interfaces for ambitious product teams.</ProfileCardBio>
      <ProfileCardFooter>
        <SocialLinks>
          {socials.map((href) => (
            <SocialLink key={href} href={href} />
          ))}
        </SocialLinks>
        <ProfileCardAction href="mailto:hello@example.com">
          <Mail aria-hidden /> Get in touch
        </ProfileCardAction>
      </ProfileCardFooter>
    </ProfileCard>
  )
}
```

### With Cover

Add a banner and the avatar overlaps it automatically. Two actions split the footer evenly.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProfileCard,
  ProfileCardAction,
  ProfileCardAvatar,
  ProfileCardBio,
  ProfileCardContent,
  ProfileCardCover,
  ProfileCardFooter,
  ProfileCardName,
  ProfileCardRole,
} from "@/components/portfolio/profile-card"
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"

export default function ProfileCardWithCover() {
  return (
    <ProfileCard className="w-full max-w-sm">
      <ProfileCardCover>
        <GenerativeArt seed="noa-cover" variant="landscape" />
      </ProfileCardCover>
      <ProfileCardAvatar initials="NV" seed="Noa Vale" />
      <ProfileCardContent>
        <ProfileCardName>Noa Vale</ProfileCardName>
        <ProfileCardRole>
          Design Engineer at <span className="text-foreground">Halcyon Labs</span>
        </ProfileCardRole>
      </ProfileCardContent>
      <ProfileCardBio>
        Nine years at the seam between product design and front-end engineering. Currently leading the design system.
      </ProfileCardBio>
      <ProfileCardFooter>
        <SocialLinks variant="pill">
          <SocialLink href="https://github.com/example" />
          <SocialLink href="https://read.cv/example" />
        </SocialLinks>
        <div className="grid w-full grid-cols-2 gap-2">
          <ProfileCardAction href="#work" variant="outline">
            See work
          </ProfileCardAction>
          <ProfileCardAction href="mailto:hello@example.com">Email me</ProfileCardAction>
        </div>
      </ProfileCardFooter>
    </ProfileCard>
  )
}
```

### Compact

A single row for sidebars, post footers and “written by” blocks. In slots narrower than 28rem the links and action move under the name.

```tsx
import { ArrowUpRight } from "lucide-react"

import {
  ProfileCard,
  ProfileCardAction,
  ProfileCardAvatar,
  ProfileCardContent,
  ProfileCardFooter,
  ProfileCardName,
  ProfileCardRole,
} from "@/components/portfolio/profile-card"
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"

export default function ProfileCardCompact() {
  return (
    <ProfileCard variant="compact" className="w-full max-w-xl">
      <ProfileCardAvatar initials="NV" seed="Noa Vale" />
      <ProfileCardContent>
        <ProfileCardName>Noa Vale</ProfileCardName>
        <ProfileCardRole>Design Engineer · Lisbon</ProfileCardRole>
      </ProfileCardContent>
      <ProfileCardFooter>
        <SocialLinks>
          <SocialLink href="https://github.com/example" />
          <SocialLink href="https://x.com/example" />
        </SocialLinks>
        <ProfileCardAction href="mailto:hello@example.com">
          Contact <ArrowUpRight aria-hidden />
        </ProfileCardAction>
      </ProfileCardFooter>
    </ProfileCard>
  )
}
```

### Team List

Stack compact cards for collaborators or a studio roster. Long roles wrap, and each card shows its own status.

```tsx
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import {
  ProfileCard,
  ProfileCardAvatar,
  ProfileCardContent,
  ProfileCardFooter,
  ProfileCardName,
  ProfileCardRole,
} from "@/components/portfolio/profile-card"

const team = [
  { name: "Noa Vale", initials: "NV", role: "Design Engineer", available: true },
  { name: "Ines Carvalho", initials: "IC", role: "Product lead — research, strategy and roadmaps", available: false },
  { name: "Sam Okafor", initials: "SO", role: "Brand & illustration", available: true },
]

export default function ProfileCardTeam() {
  return (
    <ul role="list" className="flex w-full max-w-lg flex-col gap-3">
      {team.map((member) => (
        <li key={member.name}>
          <ProfileCard variant="compact">
            <ProfileCardAvatar initials={member.initials} seed={member.name} />
            <ProfileCardContent>
              <ProfileCardName as="h3">{member.name}</ProfileCardName>
              <ProfileCardRole>{member.role}</ProfileCardRole>
            </ProfileCardContent>
            <ProfileCardFooter>
              <AvailabilityBadge variant="soft" status={member.available ? "available" : "unavailable"}>
                {member.available ? "Available" : "Booked"}
              </AvailabilityBadge>
            </ProfileCardFooter>
          </ProfileCard>
        </li>
      ))}
    </ul>
  )
}
```

## API Reference

### ProfileCard

The card. `card` stacks everything centered (link-in-bio, about pages); `compact` puts avatar,
content and footer in one row for sidebars, post footers and team lists.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"card" \| "compact"` | `"card"` | `card`: centered and stacked, for a link-in-bio page or a sidebar. `compact`: one row with the avatar on the left, for footers and author boxes; in slots narrower than 28rem the footer moves under the name. |

Also accepts every `article` prop.

### ProfileCardCover

Optional banner behind the avatar (card variant). Pass artwork or an image.

Also accepts every `div` prop.

### ProfileCardAvatar

Round photo, artwork or initials over generative art. Overlaps `ProfileCardCover` when placed right after it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `React.ReactNode` | — | Artwork used instead of `src`, e.g. `<GenerativeArt variant="portrait" />`. Fills the circle. |
| `src` | `string` | — | Photo URL. Falls back to the initials over generative art if it's missing or fails to load. |
| `alt` | `string` | `""` | Describes the photo (or the fallback). Leave empty when the name is already next to it. |
| `initials` | `string` | — | Shown over a generative orb when there is no image (or it fails to load). |
| `seed` | `string` | — | Seed for the fallback artwork. Defaults to the initials. |

Also accepts every `div` prop.

### ProfileCardContent

Groups name, role and meta. In the compact variant it's the flexible middle column.

Also accepts every `div` prop.

### ProfileCardName

Your name, as a heading (`h2` by default).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h1" \| "h2" \| "h3" \| "p" \| "span"` | `"h2"` | Heading level, or `p`/`span` where a heading would break the page outline (e.g. a sidebar or footer card). |

Also accepts every `h2` prop.

### ProfileCardRole

Job title or one-line descriptor, muted. Wraps in full; add `line-clamp-2` yourself if you need a hard limit.

Also accepts every `p` prop.

### ProfileCardLocation

Place with a small map pin, in the mono meta style.

Also accepts every `p` prop.

### ProfileCardStatus

Status row. Put an `<AvailabilityBadge />` (or anything else) in here.

Also accepts every `div` prop.

### ProfileCardBio

A sentence or two about you. In the compact variant put it inside `ProfileCardContent`; add `line-clamp-2` if you need a hard limit.

Also accepts every `p` prop.

### ProfileCardFooter

Socials and actions. Separated by a rule in the card variant; in compact a trailing column that moves under the name in slots narrower than 28rem.

Also accepts every `div` prop.

### ProfileCardAction

Primary call to action, styled as a pill button: full width and 44px tall in the card variant; compact keeps a small pill with a 44px tall touch area. Long labels wrap.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "outline"` | `"default"` | `default` for the main action, `outline` for a secondary one beside it. |

Also accepts every `a` prop.



---

# Project Card

> Composable work card with media, meta, title, summary and tags, in card, minimal or overlay style. The whole card is one link.

Category: Work · Registry item: `@portfolio-kit/project-card` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/project-card) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/project-card.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/project-card
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/project-card.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTags,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"

<ProjectCard href="/work/lumen">
  <ProjectCardMedia>
    <img src="/work/lumen.jpg" alt="" />
  </ProjectCardMedia>
  <ProjectCardContent>
    <ProjectCardMeta>
      <span>2025</span>
      <span>Halcyon Labs</span>
    </ProjectCardMeta>
    <ProjectCardTitle>Lumen</ProjectCardTitle>
    <ProjectCardDescription>A design system powering eleven products.</ProjectCardDescription>
    <ProjectCardTags tags={["Design systems", "React"]} />
  </ProjectCardContent>
</ProjectCard>
```

## Examples

### Demo

A case-study card: generative cover, meta row, title, summary and tags. The whole card is one link.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTags,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"

export default function ProjectCardDemo() {
  return (
    <ProjectCard href="#lumen" className="w-full max-w-sm">
      <ProjectCardMedia>
        <GenerativeArt seed="lumen" variant="interface" hue={20} />
      </ProjectCardMedia>
      <ProjectCardContent>
        <ProjectCardMeta>
          <span>2025</span>
          <span>Halcyon Labs</span>
        </ProjectCardMeta>
        <ProjectCardTitle>Lumen</ProjectCardTitle>
        <ProjectCardDescription>
          A design system and component platform powering eleven products and 140 engineers.
        </ProjectCardDescription>
        <ProjectCardTags tags={["Design systems", "React", "Tokens"]} />
      </ProjectCardContent>
    </ProjectCard>
  )
}
```

### Minimal

No border or background, just the cover with quiet text underneath. Suits editorial and photography portfolios.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"

export default function ProjectCardMinimal() {
  return (
    <ProjectCard variant="minimal" href="#tidewater" className="w-full max-w-sm">
      <ProjectCardMedia>
        <GenerativeArt seed="tidewater" variant="interface" hue={195} />
      </ProjectCardMedia>
      <ProjectCardContent>
        <ProjectCardMeta>
          <span>2025</span>
          <span>Product design</span>
        </ProjectCardMeta>
        <ProjectCardTitle>Tidewater</ProjectCardTitle>
        <ProjectCardDescription>Real-time grid monitoring for coastal wind farms — dense data, calm interface.</ProjectCardDescription>
      </ProjectCardContent>
    </ProjectCard>
  )
}
```

### Overlay

Text sits on the cover behind a dark scrim. Use it for image-led grids.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"

export default function ProjectCardOverlay() {
  return (
    <ProjectCard variant="overlay" href="#fieldnote" className="w-full max-w-sm">
      <ProjectCardMedia>
        <GenerativeArt seed="fieldnote" variant="bauhaus" />
      </ProjectCardMedia>
      <ProjectCardContent>
        <ProjectCardMeta>
          <span>2024</span>
          <span>Brand &amp; web</span>
        </ProjectCardMeta>
        <ProjectCardTitle>Fieldnote</ProjectCardTitle>
        <ProjectCardDescription>Identity and marketing site for a note-taking app built for researchers.</ProjectCardDescription>
      </ProjectCardContent>
    </ProjectCard>
  )
}
```

### Grid

Map your projects into a list-based grid: one column on phones, three on desktop, with the tags of each row aligned along the bottom.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTags,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"

const projects = [
  {
    slug: "lumen",
    title: "Lumen",
    year: 2025,
    client: "Halcyon Labs",
    summary: "A design system powering eleven products and 140 engineers.",
    tags: ["Design systems", "React"],
    art: "interface",
    hue: 250,
  },
  {
    slug: "tidewater",
    title: "Tidewater",
    year: 2025,
    client: "Tidewater Energy",
    summary: "Real-time grid monitoring for coastal wind farms.",
    tags: ["Data viz", "Dashboard"],
    art: "interface",
    hue: 195,
  },
  {
    slug: "orbit",
    title: "Orbit",
    year: 2024,
    client: "Open source",
    summary: "A tiny, accessible command palette for React.",
    tags: ["Open source", "a11y"],
    art: "interface",
    hue: 20,
  },
] as const

export default function ProjectCardGrid() {
  return (
    <ul role="list" className="mx-auto grid max-w-5xl gap-6 sm:grid-cols-2 lg:grid-cols-3">
      {projects.map((project) => (
        <li key={project.slug} className="flex">
          <ProjectCard href={`#${project.slug}`} className="w-full">
            <ProjectCardMedia>
              <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
            </ProjectCardMedia>
            <ProjectCardContent>
              <ProjectCardMeta>
                <span>{project.year}</span>
                <span>{project.client}</span>
              </ProjectCardMeta>
              <ProjectCardTitle>{project.title}</ProjectCardTitle>
              <ProjectCardDescription>{project.summary}</ProjectCardDescription>
              <ProjectCardTags tags={[...project.tags]} />
            </ProjectCardContent>
          </ProjectCard>
        </li>
      ))}
    </ul>
  )
}
```

### With video

Put a `<HoverVideo>` in the media slot: the artwork is the poster, and a muted clip plays while the card is hovered or focused.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { HoverVideo } from "@/components/portfolio/hover-video"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTags,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"

export default function ProjectCardWithVideo() {
  return (
    <ProjectCard href="#orbit" className="w-full max-w-sm">
      <ProjectCardMedia>
        {/* Your clip: a file in public/ ("/work/orbit.mp4") or a CDN URL. The demo clip sits next to the docs preview. */}
        <HoverVideo src="media/showreel.mp4">
          <GenerativeArt seed="orbit-motion" variant="interface" hue={20} />
        </HoverVideo>
      </ProjectCardMedia>
      <ProjectCardContent>
        <ProjectCardMeta>
          <span>2024</span>
          <span>Open source</span>
        </ProjectCardMeta>
        <ProjectCardTitle>Orbit</ProjectCardTitle>
        <ProjectCardDescription>A tiny, accessible command palette, with motion that never gets in the way.</ProjectCardDescription>
        <ProjectCardTags tags={["Motion", "React", "a11y"]} />
      </ProjectCardContent>
    </ProjectCard>
  )
}
```

## API Reference

### ProjectCard

Root `<article>`. Holds the variant and link for the parts inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"card" \| "minimal" \| "overlay"` | `"card"` | `card`: a bordered card with the media on top. `minimal`: no border or background, just the media and text. `overlay`: text on the media behind a dark scrim (keep the copy short). |
| `href` | `string` | — | Makes the whole card one link (rendered on the title, stretched over the card). Absolute URLs open in a new tab. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to the title link when `href` opens in a new tab. Translate it here. |

Also accepts every `article` prop.

### ProjectCardMedia

Cover slot. Put an `<img>`, `<video>` or `<GenerativeArt />` inside; direct `<img>`/`<video>`
children are cropped to fill. `card` is 16:10, `minimal` 4:3 (override with e.g.
`className="aspect-[4/5]"`); in `overlay` it fills the whole card.

Also accepts every `div` prop.

### ProjectCardContent

Text column: meta, title, description and tags, in that order. In `overlay` it sits at the bottom of the card.

Also accepts every `div` prop.

### ProjectCardMeta

Small mono line above the title. Pass `<span>`s (year, client, role); they're separated by slashes.

Also accepts every `div` prop.

### ProjectCardTitle

The card's heading. With `href` on the card it holds the link and an arrow chip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level. Match your page outline (`h2` when cards sit directly under the page title). |

Also accepts every `h3` prop.

### ProjectCardDescription

Short summary. Clamped to three lines so rows of cards stay even.

Also accepts every `p` prop.

### ProjectCardTags

Tag chips pinned to the bottom of the card, so tags line up across a row of cards.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tags` (required) | `string[]` | — | Short labels such as stack, discipline or deliverables. Two or three read best. |
| `label` | `string` | `"Tags"` | Accessible name of the tag list. Translate it here. |

Also accepts every `ul` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)



---

# Project Carousel

> Scroll-snap carousel for projects with mouse drag, arrow keys, previous/next buttons, a slide counter and a progress bar. No dependencies.

Category: Work · Registry item: `@portfolio-kit/project-carousel` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/project-carousel) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/project-carousel.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/project-carousel
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/project-carousel.tsx` and the kit items it uses: `typography`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  ProjectCard,
  ProjectCardMedia,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import {
  ProjectCarousel,
  ProjectCarouselControls,
  ProjectCarouselCounter,
  ProjectCarouselItem,
  ProjectCarouselNext,
  ProjectCarouselPrevious,
  ProjectCarouselProgress,
  ProjectCarouselViewport,
} from "@/components/portfolio/project-carousel"

<ProjectCarousel label="Selected work">
  <ProjectCarouselViewport>
    <ProjectCarouselItem>
      <ProjectCard href="/work/lumen">
        <ProjectCardMedia>
          <img src="/lumen.jpg" alt="" />
        </ProjectCardMedia>
        <ProjectCardTitle>Lumen</ProjectCardTitle>
      </ProjectCard>
    </ProjectCarouselItem>
  </ProjectCarouselViewport>
  <ProjectCarouselControls>
    <ProjectCarouselCounter />
    <ProjectCarouselProgress />
    <ProjectCarouselPrevious />
    <ProjectCarouselNext />
  </ProjectCarouselControls>
</ProjectCarousel>
```

## Examples

### Demo

A scroll-snap row of projects that lines up with the page container and runs off the right edge. Drag, swipe, or use the arrow keys or buttons.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import {
  ProjectCarousel,
  ProjectCarouselControls,
  ProjectCarouselCounter,
  ProjectCarouselItem,
  ProjectCarouselNext,
  ProjectCarouselPrevious,
  ProjectCarouselProgress,
  ProjectCarouselViewport,
} from "@/components/portfolio/project-carousel"
import {
  Container,
  Section,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const projects = [
  { slug: "tidewater", title: "Tidewater", year: 2025, role: "Product design", art: "interface", hue: 195 },
  { slug: "lumen", title: "Lumen", year: 2025, role: "Design lead", art: "interface", hue: 250 },
  { slug: "fieldnote", title: "Fieldnote", year: 2024, role: "Brand & web", art: "bauhaus", hue: 132 },
  { slug: "orbit", title: "Orbit Analytics", year: 2024, role: "Front-end", art: "interface", hue: 20 },
  { slug: "kiln", title: "Kiln", year: 2023, role: "Design & build", art: "landscape", hue: 330 },
] as const

export default function ProjectCarouselDemo() {
  return (
    <Section size={false}>
      <ProjectCarousel label="Selected work">
        <Container>
          <SectionHeader>
            <SectionEyebrow index={1}>Selected work</SectionEyebrow>
            <SectionTitle>Recent projects</SectionTitle>
          </SectionHeader>
        </Container>
        <ProjectCarouselViewport inset="container">
          {projects.map((project) => (
            <ProjectCarouselItem key={project.slug}>
              <ProjectCard variant="minimal" href={`#${project.slug}`}>
                <ProjectCardMedia className="aspect-[4/5]">
                  <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
                </ProjectCardMedia>
                <ProjectCardContent>
                  <ProjectCardMeta>
                    <span>{project.year}</span>
                    <span>{project.role}</span>
                  </ProjectCardMeta>
                  <ProjectCardTitle>{project.title}</ProjectCardTitle>
                </ProjectCardContent>
              </ProjectCard>
            </ProjectCarouselItem>
          ))}
        </ProjectCarouselViewport>
        <Container>
          <ProjectCarouselControls>
            <ProjectCarouselCounter />
            <ProjectCarouselProgress />
            <div className="flex gap-2">
              <ProjectCarouselPrevious />
              <ProjectCarouselNext />
            </div>
          </ProjectCarouselControls>
        </Container>
      </ProjectCarousel>
    </Section>
  )
}
```

### Featured

Large overlay slides with the controls above them, for three or four main case studies.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import {
  ProjectCarousel,
  ProjectCarouselControls,
  ProjectCarouselCounter,
  ProjectCarouselItem,
  ProjectCarouselNext,
  ProjectCarouselPrevious,
  ProjectCarouselProgress,
  ProjectCarouselViewport,
} from "@/components/portfolio/project-carousel"

const caseStudies = [
  {
    slug: "lumen",
    title: "Lumen",
    client: "Halcyon Labs",
    summary: "A design system powering eleven products and 140 engineers.",
    art: "interface",
    hue: 250,
  },
  {
    slug: "tidewater",
    title: "Tidewater",
    client: "Tidewater Energy",
    summary: "Real-time grid monitoring for coastal wind farms.",
    art: "interface",
    hue: 195,
  },
  {
    slug: "fieldnote",
    title: "Fieldnote",
    client: "Fieldnote Inc.",
    summary: "Identity and marketing site for a note-taking app built for researchers.",
    art: "bauhaus",
    hue: 132,
  },
  {
    slug: "orbit",
    title: "Orbit Analytics",
    client: "Orbit",
    summary: "Privacy-first product analytics with a query builder anyone can use.",
    art: "interface",
    hue: 20,
  },
] as const

export default function ProjectCarouselFeatured() {
  return (
    <ProjectCarousel label="Case studies" className="mx-auto w-full max-w-5xl">
      <ProjectCarouselControls className="justify-between">
        <h2 className="font-heading text-2xl md:text-3xl">Case studies</h2>
        <div className="flex gap-2">
          <ProjectCarouselPrevious />
          <ProjectCarouselNext />
        </div>
      </ProjectCarouselControls>
      <ProjectCarouselViewport>
        {caseStudies.map((project) => (
          <ProjectCarouselItem key={project.slug} size="lg">
            <ProjectCard variant="overlay" href={`#${project.slug}`}>
              <ProjectCardMedia>
                <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
              </ProjectCardMedia>
              <ProjectCardContent>
                <ProjectCardMeta>
                  <span>{project.client}</span>
                </ProjectCardMeta>
                <ProjectCardTitle>{project.title}</ProjectCardTitle>
                <ProjectCardDescription>{project.summary}</ProjectCardDescription>
              </ProjectCardContent>
            </ProjectCard>
          </ProjectCarouselItem>
        ))}
      </ProjectCarouselViewport>
      <ProjectCarouselControls>
        <ProjectCarouselProgress />
        <ProjectCarouselCounter />
      </ProjectCarouselControls>
    </ProjectCarousel>
  )
}
```

### Compact

Small cards, four across on desktop. Works as a “more work” row at the end of a case study.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import {
  ProjectCarousel,
  ProjectCarouselControls,
  ProjectCarouselCounter,
  ProjectCarouselItem,
  ProjectCarouselNext,
  ProjectCarouselPrevious,
  ProjectCarouselProgress,
  ProjectCarouselViewport,
} from "@/components/portfolio/project-carousel"

const moreWork = [
  { slug: "orbit", title: "Orbit Analytics", year: 2024, art: "interface", hue: 20 },
  { slug: "kiln", title: "Kiln", year: 2023, art: "landscape", hue: 330 },
  { slug: "paperplane", title: "Paperplane", year: 2023, art: "rings", hue: 290 },
  { slug: "meridian", title: "Meridian", year: 2022, art: "bauhaus", hue: 115 },
  { slug: "northpeak", title: "Northpeak", year: 2021, art: "interface", hue: 150 },
  { slug: "atlas", title: "Atlas & Co", year: 2021, art: "bauhaus", hue: 60 },
] as const

export default function ProjectCarouselCompact() {
  return (
    <ProjectCarousel label="More work" className="mx-auto w-full max-w-5xl">
      <ProjectCarouselViewport>
        {moreWork.map((project) => (
          <ProjectCarouselItem key={project.slug} size="sm">
            <ProjectCard href={`#${project.slug}`}>
              <ProjectCardMedia>
                <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
              </ProjectCardMedia>
              <ProjectCardContent>
                <ProjectCardMeta>
                  <span>{project.year}</span>
                </ProjectCardMeta>
                <ProjectCardTitle>{project.title}</ProjectCardTitle>
              </ProjectCardContent>
            </ProjectCard>
          </ProjectCarouselItem>
        ))}
      </ProjectCarouselViewport>
      <ProjectCarouselControls>
        <ProjectCarouselCounter />
        <ProjectCarouselProgress />
        <div className="flex gap-2">
          <ProjectCarouselPrevious />
          <ProjectCarouselNext />
        </div>
      </ProjectCarouselControls>
    </ProjectCarousel>
  )
}
```

## API Reference

### ProjectCarousel

Root `<section>` that tracks the scroll position. Compose a `ProjectCarouselViewport` of
`ProjectCarouselItem`s with any `ProjectCarouselControls` (counter, progress, prev/next)
above, below or inside a `Container`. They all control the same viewport.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Projects"` | Accessible name of the carousel region, e.g. "Selected work". |

Also accepts every `section` prop.

### ProjectCarouselViewport

The scrolling `<ul>` of slides. Native scroll-snap: swipe on touch, drag with a mouse (the click
that ends a drag doesn't open the slide's link), or focus it and use ←/→ (one slide, mirrored in
RTL) and Home/End. Smooth scrolling is off under reduced motion. In print the slides wrap into a
three-column grid so every one prints; change the count with e.g. `className="print:grid-cols-4"`.
The default `aria-label` ("Slides — use arrow keys to navigate") can be replaced like any other prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `"none" \| "container"` | `"none"` | `none`: slides stay inside the carousel's own box. `container`: the viewport spans the full width, the first slide lines up with a page `Container` and later slides bleed off the screen edge. Use it with `<Section size={false}>` and wrap headers/controls in a matching `Container`. |
| `size` | `"sm" \| "default" \| "lg" \| "full"` | `"default"` | With `inset="container"`: the `Container` size to align with (same names as `Container`). |

Also accepts every `ul` prop.

### ProjectCarouselItem

One slide (`<li>`), announced as a slide labelled "2 of 5" (pass `aria-label` to change it). Its
child, usually a `ProjectCard`, is stretched to the slide height. Render slides as direct
children of `ProjectCarouselViewport` (a `.map()` is fine) so they can be numbered.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg" \| "full"` | `"default"` | Slide width. `sm` ≈ 1.4 / 2.4 / 4 per view (phone / tablet / desktop), `default` ≈ 1.2 / 1.7 / 3, `lg` ≈ 1.1 / 1.5 / 1.8. A peek of the next slide shows that the row scrolls. `full` is one per view. |

Also accepts every `li` prop.

### ProjectCarouselControls

A flex row for the counter, progress bar and buttons (or a heading plus buttons). Order them freely. The controls hide themselves in print; a heading stays.

Also accepts every `div` prop.

### ProjectCarouselCounter

"01 / 06" in mono. Screen readers hear "Slide 1 of 6", announced politely as the position changes. Hidden in print.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Slide {current} of {count}"` | What screen readers hear; `{current}` and `{count}` are replaced. Translate it here. |

Also accepts every `p` prop.

### ProjectCarouselProgress

Scrollbar-like bar: the thumb is as wide as the visible fraction and moves with scroll. Hidden in print.

Also accepts every `div` prop.

### ProjectCarouselPrevious

Scrolls back one slide; marked `aria-disabled` at the start (it stays focusable). The default label is "Previous project"; pass
`aria-label` to change it (e.g. "Previous frame") and children to swap the icon. Hidden in print, like the
counter and progress bar.

Also accepts every `button` prop.

### ProjectCarouselNext

Scrolls forward one slide; `aria-disabled` at the end. Same label/icon overrides as `ProjectCarouselPrevious`.

Also accepts every `button` prop.

## Used in templates

- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)



---

# Project Grid

> Responsive grid for project cards: even rows, staggered columns, or a featured first project that spans two columns.

Category: Work · Registry item: `@portfolio-kit/project-grid` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/project-grid) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/project-grid.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/project-grid
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/project-grid.tsx`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import {
  ProjectGrid,
  ProjectGridItem,
} from "@/components/portfolio/project-grid"

<ProjectGrid>
  <ProjectGridItem>
    <ProjectCard href="/work/lumen">
      <ProjectCardMedia>
        <img src="/lumen.jpg" alt="" />
      </ProjectCardMedia>
      <ProjectCardContent>
        <ProjectCardTitle>Lumen</ProjectCardTitle>
        <ProjectCardDescription>A design system for eleven products.</ProjectCardDescription>
      </ProjectCardContent>
    </ProjectCard>
  </ProjectGridItem>
</ProjectGrid>
```

## Examples

### Demo

Project cards in a responsive grid: one column on phones, two on tablets, three on desktop, with equal-height rows.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTags,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import { ProjectGrid, ProjectGridItem } from "@/components/portfolio/project-grid"

const projects = [
  { slug: "lumen", title: "Lumen", year: 2025, client: "Halcyon Labs", summary: "A design system powering eleven products and 140 engineers.", tags: ["Design systems", "React"], art: "interface", hue: 250 },
  { slug: "tidewater", title: "Tidewater", year: 2025, client: "Tidewater Energy", summary: "Real-time grid monitoring for coastal wind farms.", tags: ["Data viz", "Dashboard"], art: "interface", hue: 195 },
  { slug: "fieldnote", title: "Fieldnote", year: 2024, client: "Fieldnote Inc.", summary: "Identity and marketing site for a note-taking app built for researchers.", tags: ["Branding", "Next.js"], art: "bauhaus", hue: 132 },
  { slug: "orbit", title: "Orbit Analytics", year: 2024, client: "Orbit", summary: "Privacy-first product analytics with a query builder anyone can use.", tags: ["TypeScript", "Charts"], art: "interface", hue: 20 },
  { slug: "kiln", title: "Kiln", year: 2023, client: "Kiln Ceramics", summary: "A storefront for a small ceramics studio, shot and built in three weeks.", tags: ["Shopify", "Photography"], art: "landscape", hue: 330 },
  { slug: "paperplane", title: "Paperplane", year: 2023, client: "Open source", summary: "A tiny, typed animation library for React.", tags: ["Open source", "Animation"], art: "rings", hue: 290 },
] as const

export default function ProjectGridDemo() {
  return (
    <ProjectGrid className="mx-auto max-w-6xl">
      {projects.map((project) => (
        <ProjectGridItem key={project.slug}>
          <ProjectCard href={`#${project.slug}`}>
            <ProjectCardMedia>
              <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
            </ProjectCardMedia>
            <ProjectCardContent>
              <ProjectCardMeta>
                <span>{project.year}</span>
                <span>{project.client}</span>
              </ProjectCardMeta>
              <ProjectCardTitle>{project.title}</ProjectCardTitle>
              <ProjectCardDescription>{project.summary}</ProjectCardDescription>
              <ProjectCardTags tags={[...project.tags]} />
            </ProjectCardContent>
          </ProjectCard>
        </ProjectGridItem>
      ))}
    </ProjectGrid>
  )
}
```

### Staggered

Two columns with the second one pushed down for an editorial rhythm. Pairs best with minimal cards.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import { ProjectGrid, ProjectGridItem } from "@/components/portfolio/project-grid"

const projects = [
  { slug: "tidewater", title: "Tidewater", year: 2025, role: "Product design", summary: "Real-time grid monitoring for coastal wind farms — dense data, calm interface.", art: "interface", hue: 195 },
  { slug: "fieldnote", title: "Fieldnote", year: 2024, role: "Brand & web", summary: "Identity and marketing site for a note-taking app built for researchers.", art: "bauhaus", hue: 132 },
  { slug: "kiln", title: "Kiln", year: 2023, role: "Design & build", summary: "A storefront for a small ceramics studio, shot and built in three weeks.", art: "landscape", hue: 330 },
  { slug: "orbit", title: "Orbit Analytics", year: 2024, role: "Front-end", summary: "Privacy-first product analytics with a query builder anyone can use.", art: "interface", hue: 20 },
] as const

export default function ProjectGridStaggered() {
  return (
    <ProjectGrid columns={2} variant="staggered" className="mx-auto max-w-5xl">
      {projects.map((project) => (
        <ProjectGridItem key={project.slug}>
          <ProjectCard variant="minimal" href={`#${project.slug}`}>
            <ProjectCardMedia className="aspect-[4/5]">
              <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
            </ProjectCardMedia>
            <ProjectCardContent>
              <ProjectCardMeta>
                <span>{project.year}</span>
                <span>{project.role}</span>
              </ProjectCardMeta>
              <ProjectCardTitle>{project.title}</ProjectCardTitle>
              <ProjectCardDescription>{project.summary}</ProjectCardDescription>
            </ProjectCardContent>
          </ProjectCard>
        </ProjectGridItem>
      ))}
    </ProjectGrid>
  )
}
```

### Featured

The first project takes a 2×2 block so your main case study leads. Three projects fill it exactly.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardDescription,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import { ProjectGrid, ProjectGridItem } from "@/components/portfolio/project-grid"

const projects = [
  { slug: "lumen", title: "Lumen", client: "Halcyon Labs", summary: "A design system and component platform powering eleven products and 140 engineers.", art: "interface", hue: 250 },
  { slug: "tidewater", title: "Tidewater", client: "Tidewater Energy", summary: "Real-time grid monitoring for coastal wind farms.", art: "interface", hue: 195 },
  { slug: "fieldnote", title: "Fieldnote", client: "Fieldnote Inc.", summary: "Identity and site for a note-taking app built for researchers.", art: "bauhaus", hue: 132 },
] as const

export default function ProjectGridFeatured() {
  return (
    <ProjectGrid variant="featured" className="mx-auto max-w-6xl">
      {projects.map((project) => (
        <ProjectGridItem key={project.slug}>
          <ProjectCard href={`#${project.slug}`}>
            <ProjectCardMedia>
              <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
            </ProjectCardMedia>
            <ProjectCardContent>
              <ProjectCardMeta>
                <span>{project.client}</span>
              </ProjectCardMeta>
              <ProjectCardTitle>{project.title}</ProjectCardTitle>
              <ProjectCardDescription>{project.summary}</ProjectCardDescription>
            </ProjectCardContent>
          </ProjectCard>
        </ProjectGridItem>
      ))}
    </ProjectGrid>
  )
}
```

### Filterable

Pair the grid with filter chips; `ProjectGridEmpty` covers categories with nothing in them yet.

```tsx
import * as React from "react"

import { FilterChip, FilterChips } from "@/components/portfolio/filter-chips"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import { ProjectGrid, ProjectGridEmpty, ProjectGridItem } from "@/components/portfolio/project-grid"

const categories = ["All", "Product", "Brand", "Open source"] as const

const projects = [
  { slug: "lumen", title: "Lumen", year: 2025, category: "Product", art: "interface", hue: 250 },
  { slug: "tidewater", title: "Tidewater", year: 2025, category: "Product", art: "interface", hue: 195 },
  { slug: "fieldnote", title: "Fieldnote", year: 2024, category: "Brand", art: "bauhaus", hue: 132 },
] as const

export default function ProjectGridFilterable() {
  const [category, setCategory] = React.useState<string>("All")
  const visible = category === "All" ? projects : projects.filter((p) => p.category === category)

  return (
    <div className="mx-auto flex max-w-6xl flex-col gap-8">
      <FilterChips type="single" required value={category} onValueChange={setCategory} aria-label="Filter by category">
        {categories.map((c) => (
          <FilterChip
            key={c}
            value={c}
            label={c}
            count={c === "All" ? projects.length : projects.filter((p) => p.category === c).length}
          />
        ))}
      </FilterChips>
      {/* Announce the result count when the filter changes. */}
      <p aria-live="polite" className="sr-only">
        {visible.length === 1 ? "1 project" : `${visible.length} projects`}
      </p>
      {visible.length === 0 ? (
        <ProjectGridEmpty>No {category.toLowerCase()} projects yet — check back soon.</ProjectGridEmpty>
      ) : (
        <ProjectGrid>
          {visible.map((project) => (
            <ProjectGridItem key={project.slug}>
              <ProjectCard href={`#${project.slug}`}>
                <ProjectCardMedia>
                  <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
                </ProjectCardMedia>
                <ProjectCardContent>
                  <ProjectCardMeta>
                    <span>{project.year}</span>
                    <span>{project.category}</span>
                  </ProjectCardMeta>
                  <ProjectCardTitle>{project.title}</ProjectCardTitle>
                </ProjectCardContent>
              </ProjectCard>
            </ProjectGridItem>
          ))}
        </ProjectGrid>
      )}
    </div>
  )
}
```

## API Reference

### ProjectGrid

A `<ul>` grid. Wrap each card in `ProjectGridItem` (an `<li>`); cards stretch to equal height per row.
Works with `ProjectCard` or any card that fills its cell.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `2 \| 3` | `3` | Columns on wide screens. `3` goes 1 → 2 (from `sm`) → 3 (from `lg`); `2` goes 1 → 2 from `md`. |
| `variant` | `"default" \| "staggered" \| "featured"` | `"default"` | `default`: even rows. `staggered`: every second (2 cols) or middle (3 cols) column is pushed down for an editorial rhythm; pairs well with `minimal` cards. `featured`: the first item spans the full row (2 cols) or a 2×2 block (3 cols), so three items fill a 3-column grid exactly. |

Also accepts every `ul` prop.

### ProjectGridItem

One cell (`<li>`). Its single child is stretched to the row height.

Also accepts every `li` prop.

### ProjectGridEmpty

Placeholder for a grid with nothing to show (e.g. a filter with no matches). Render it *instead of*
the grid. It's a polite live region, so screen readers hear the message when a filter empties the list.

Also accepts every `div` prop.



---

# Project List

> Projects as large text rows, with a preview image that follows the cursor on desktop and thumbnails on mobile.

Category: Work · Registry item: `@portfolio-kit/project-list` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/project-list) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/project-list.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/project-list
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/project-list.tsx` and the kit items it uses: `typography`, `use-fine-pointer`, `use-media-query`, `use-reduced-motion`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import {
  ProjectList,
  ProjectListItem,
} from "@/components/portfolio/project-list"

<ProjectList numbered>
  <ProjectListItem
    href="/work/lumen"
    heading="Lumen"
    client="Halcyon Labs"
    discipline="Design system"
    year={2025}
    preview={<img src="/lumen.jpg" alt="" />}
  />
</ProjectList>
```

## Examples

### Demo

A work index with large numbered titles. A preview follows the cursor on desktop; phones get inline thumbnails.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { ProjectList, ProjectListItem } from "@/components/portfolio/project-list"

const projects = [
  { slug: "lumen", title: "Lumen", client: "Halcyon Labs", role: "Design lead", year: 2025, art: "interface", hue: 250 },
  { slug: "tidewater", title: "Tidewater", client: "Tidewater Energy", role: "Product design", year: 2025, art: "interface", hue: 195 },
  { slug: "fieldnote", title: "Fieldnote", client: "Fieldnote Inc.", role: "Brand & web", year: 2024, art: "bauhaus", hue: 132 },
  { slug: "orbit", title: "Orbit Analytics", client: "Orbit", role: "Front-end", year: 2024, art: "interface", hue: 20 },
] as const

export default function ProjectListDemo() {
  return (
    <ProjectList numbered className="mx-auto max-w-5xl">
      {projects.map((project) => (
        <ProjectListItem
          key={project.slug}
          href={`#${project.slug}`}
          heading={project.title}
          client={project.client}
          discipline={project.role}
          year={project.year}
          preview={<GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />}
        />
      ))}
    </ProjectList>
  )
}
```

### Text Only

No previews and no numbers, just type. Rows without an `href` render as plain text for work that isn't public yet.

```tsx
import { ProjectList, ProjectListItem } from "@/components/portfolio/project-list"

export default function ProjectListTextOnly() {
  return (
    <ProjectList preview={false} className="mx-auto max-w-5xl">
      <ProjectListItem href="#kiln" heading="Kiln" client="Kiln Ceramics" discipline="Design & build" year={2023} />
      <ProjectListItem href="#paperplane" heading="Paperplane" client="Open source" discipline="Maintainer" year={2023} />
      <ProjectListItem heading="Northpeak" client="Under NDA" discipline="Product design" year="Ongoing" />
    </ProjectList>
  )
}
```

### In a Section

The index as a full homepage section, with a split header and a link through to the archive.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { ProjectList, ProjectListItem } from "@/components/portfolio/project-list"
import {
  Section,
  SectionContent,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const projects = [
  { slug: "tidewater", title: "Tidewater", client: "Tidewater Energy", role: "Product design", year: 2025, art: "interface", hue: 195 },
  { slug: "fieldnote", title: "Fieldnote", client: "Fieldnote Inc.", role: "Brand & web", year: 2024, art: "bauhaus", hue: 132 },
  { slug: "kiln", title: "Kiln", client: "Kiln Ceramics", role: "Design & build", year: 2023, art: "landscape", hue: 330 },
] as const

export default function ProjectListInASection() {
  return (
    <Section>
      <SectionHeader align="split">
        <div className="flex flex-col gap-4">
          <SectionEyebrow index={2}>Index</SectionEyebrow>
          <SectionTitle>Selected projects</SectionTitle>
        </div>
        <ArrowLink href="#archive">View the full archive</ArrowLink>
      </SectionHeader>
      <SectionContent>
        <ProjectList>
          {projects.map((project) => (
            <ProjectListItem
              key={project.slug}
              href={`#${project.slug}`}
              heading={project.title}
              client={project.client}
              discipline={project.role}
              year={project.year}
              preview={<GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />}
            />
          ))}
        </ProjectList>
      </SectionContent>
    </Section>
  )
}
```

## API Reference

### ProjectList

The index (`<ul>`). Put `ProjectListItem`s inside. Hovering or keyboard-focusing a row dims the
others; rows with a `preview` feed the floating cursor preview.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `numbered` | `boolean` | `false` | Show "01." index numbers before each title (CSS counters, so items need no props). |
| `preview` | `boolean` | `true` | Floating preview that follows the cursor. Only on hover-capable fine pointers from `md` up, and never when the user prefers reduced motion. Phones get small inline thumbnails instead. |
| `previewClassName` | `string` | — | Classes for the floating preview card (size, radius, shadow). |

Also accepts every `ul` prop.

### ProjectListItem

One row (`<li>`): index, title, client, discipline, year and an arrow. On phones the columns
collapse into a thumbnail, the title and a one-line meta.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `React.ReactNode` | — | Project name, set large in the heading font. Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `href` | `string` | — | Makes the whole row a link. Rows without one render as plain text (work that isn't public yet). |
| `external` | `boolean` | — | Open in a new tab. Auto-detected for absolute URLs. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added to the link when it opens in a new tab. Translate it here. |
| `client` | `React.ReactNode` | — | Client or company. Shown from `md` up (and in the mobile meta line). |
| `discipline` | `React.ReactNode` | — | Role or discipline, e.g. "Brand & web". Shown from `lg` up (and in the mobile meta line). |
| `year` | `number \| string` | — | Year, right-aligned. A four-digit year is wrapped in `<time>`; any other string ("Ongoing") renders as-is. |
| `preview` | `React.ReactNode` | — | Artwork or image for the floating preview and the mobile thumbnail. Decorative, so it's hidden from assistive tech. |
| `index` | `React.ReactNode` | — | Override the automatic "01." index (requires `numbered` on the list). |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the project name. |

Also accepts every `li` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)



---

# Prose

> Article typography for blog posts and case studies: headings, lists, quotes, code, figures, tables and footnotes styled from your theme, with no typography plugin.

Category: Content · Registry item: `@portfolio-kit/prose` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/prose) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/prose.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/prose
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/prose.tsx`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { Prose, proseVariants } from "@/components/portfolio/prose"
```

## Examples

### Demo

A blog post body: headings, a pull quote, lists, inline and block code, a captioned figure and footnotes — the HTML your Markdown renderer already outputs.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { KbdShortcut } from "@/components/portfolio/kbd"
import { Prose } from "@/components/portfolio/prose"

export default function ProseDemo() {
  return (
    <Prose className="mx-auto">
      <p>
        Every design system starts as a folder of colors. Two years later it&rsquo;s a dependency for eleven products,
        and a renamed token can break a checkout page nobody on your team has ever opened.
        <sup>
          <a href="#fn-1" id="fnref-1" data-footnote-ref aria-describedby="footnotes-label">
            1
          </a>
        </sup>
      </p>
      <p>
        The fix isn&rsquo;t more process. It&rsquo;s treating tokens the way you&rsquo;d treat any other{" "}
        <a href="#versioning">public API</a>: versioned, deprecated slowly, and migrated with tools instead of
        announcements.
      </p>

      <h2 id="versioning">Version the contract, not the files</h2>
      <p>
        Consumers don&rsquo;t care that <code>color.blue.600</code> moved to a new file. They care whether{" "}
        <code>--accent</code> still means the same thing tomorrow. So we split the two:
      </p>
      <ul>
        <li>
          <strong>Primitive tokens</strong> are an implementation detail and can change in any release.
        </li>
        <li>
          <strong>Semantic tokens</strong> are the API. Renaming one is a major version.
        </li>
        <li>
          Every deprecated token keeps working for two minors and logs a warning with its replacement.
        </li>
      </ul>

      <blockquote>
        <p>If a token rename needs a Slack announcement, it should have been a codemod.</p>
        <cite>Design systems team, Halcyon Labs</cite>
      </blockquote>

      <h3>Codemods over changelogs</h3>
      <p>Each breaking change ships with a transform. Teams upgrade by running one command:</p>
      <pre>
        <code>{`npx @halcyon/tokens migrate --from 3 --to 4
✔ 214 files scanned
✔ 38 tokens renamed (--brand-* → --accent-*)`}</code>
      </pre>

      <figure>
        <GenerativeArt seed="tokens-are-an-api" variant="interface" className="aspect-[16/9]" />
        <figcaption>Fig. 1 — Semantic tokens sit between primitives and the products that consume them.</figcaption>
      </figure>

      <h3>What it cost</h3>
      <table>
        <thead>
          <tr>
            <th>Release</th>
            <th>Breaking tokens</th>
            <th>Manual fixes</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>v2 → v3, no codemods</td>
            <td>41</td>
            <td>~300</td>
          </tr>
          <tr>
            <td>v3 → v4, with codemods</td>
            <td>38</td>
            <td>6</td>
          </tr>
        </tbody>
      </table>

      <p>
        Press <KbdShortcut keys={["mod", "k"]} size="md" /> in any product and search &ldquo;tokens&rdquo; to see the live catalog.
      </p>

      <section data-footnotes>
        <h2 id="footnotes-label">Notes</h2>
        <ol>
          <li id="fn-1">
            True story: a <mark>border-radius token</mark> rename once took down a partner&rsquo;s embedded widget.{" "}
            <a href="#fnref-1" data-footnote-backref aria-label="Back to reference 1">
              ↩
            </a>
          </li>
        </ol>
      </section>
    </Prose>
  )
}
```

### Case study chapter

Rendered Markdown inside a page section: `size="lg"` for an essay-like read, and a wrapped component (the result stats) that keeps its own styling.

```tsx
import { Prose } from "@/components/portfolio/prose"
import { Section, SectionEyebrow, SectionHeader, SectionTitle } from "@/components/portfolio/section"

const results = [
  { value: "−38%", label: "Checkout drop-off" },
  { value: "2.1s", label: "Faster first paint" },
  { value: "6", label: "Manual fixes per release" },
]

export default function ProseCaseStudy() {
  return (
    <Section size="sm">
      <SectionHeader>
        <SectionEyebrow index={2}>The approach</SectionEyebrow>
        <SectionTitle>Fewer screens, clearer steps</SectionTitle>
      </SectionHeader>
      <Prose size="lg" className="mt-10">
        <p>
          The old checkout asked for fourteen things across five screens. We cut it to three steps by asking only for what
          the ferry operator actually needs at booking time, and moving everything else to the ticket email.
        </p>
        <h3>What we kept</h3>
        <ul>
          <li>Route and date on one screen, with the next three sailings shown up front.</li>
          <li>A single passenger form that remembers returning travellers.</li>
          <li>Apple Pay and Google Pay before the card form, not after it.</li>
        </ul>
        {/* A wrapper <div> opts out of Prose styling, so kit components look like themselves. */}
        <div className="grid grid-cols-3 gap-4 border-y py-6">
          {results.map((r) => (
            <div key={r.label}>
              <p className="font-heading text-3xl">{r.value}</p>
              <p className="mt-1 font-mono text-xs text-muted-foreground">{r.label}</p>
            </div>
          ))}
        </div>
        <p>
          The biggest win wasn&rsquo;t a screen we designed. It was the eleven fields we <em>deleted</em>.
        </p>
      </Prose>
    </Section>
  )
}
```

## API Reference

### Prose

Wrap rendered Markdown/MDX (or hand-written HTML) to give it article typography: `h2`–`h4`, paragraphs,
lists, `blockquote` (with an optional `cite`), inline `code` and `pre`, `figure`/`figcaption`, tables, `hr`,
`mark`, `kbd` and GitHub-style footnotes. Only direct children and the text inside them are styled —
wrap a component in a `<div>` and it keeps its own look (kit `Kbd`/`KbdShortcut` keycaps keep theirs
inline too). The measure is capped at `34em`, about 70 characters per line at any `size`; override it
with `className="max-w-none"` when the page sets its own column. Code blocks and tables that scroll
sideways become keyboard-focusable and named automatically; in print they wrap instead of scrolling.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg" \| null` | `"default"` | Base size; headings, spacing, code and captions scale with it. `sm` for notes and sidebars, `lg` for essays. |
| `codeLabel` | `string` | `"Code"` | Accessible name for a code block while it scrolls sideways (and is a Tab stop). Translate it here. |
| `tableLabel` | `string` | `"Table"` | Accessible name for a scrolling table without a `<caption>` or label of its own. Translate it here. |

Also accepts every `div` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)



---

# Repo Card

> GitHub-style repository card with owner/name, description, language, stars, forks, last update and topics. The whole card is one link.

Category: Content · Registry item: `@portfolio-kit/repo-card` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/repo-card) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/repo-card.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/repo-card
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/repo-card.tsx` and the kit items it uses: `brand-icons`, `format`, `typography`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { RepoCard, RepoLanguage, languageColors } from "@/components/portfolio/repo-card"
```

## Examples

### Demo

Pin an open-source project: owner/name, description, topics, language, stars, forks and last update. The whole card links to the repo.

```tsx
import { RepoCard } from "@/components/portfolio/repo-card"

export default function RepoCardDemo() {
  return (
    <RepoCard
      owner="example"
      name="paperplane"
      href="#paperplane"
      description="A tiny, typed animation library for React. Springs, gestures and layout transitions in 4 kB."
      topics={["react", "animation", "spring-physics"]}
      language="TypeScript"
      stars={4120}
      forks={186}
      updatedAt="2026-02-27T09:00:00Z"
      // Pinned so the demo reads "3 days ago" — omit to use the current time.
      now="2026-03-02T09:00:00Z"
      className="w-full max-w-md"
    />
  )
}
```

### Grid

Pinned repositories in a two-column grid, including template and archived badges.

```tsx
import type * as React from "react"

import { RepoCard } from "@/components/portfolio/repo-card"

const repos: React.ComponentProps<typeof RepoCard>[] = [
  {
    name: "paperplane",
    description: "A tiny, typed animation library for React. Springs, gestures and layout transitions in 4 kB.",
    language: "TypeScript",
    stars: 4120,
    forks: 186,
    updatedAt: "2026-02-27T09:00:00Z",
  },
  {
    name: "tokenize",
    description: "Compile design tokens to CSS, Swift and Kotlin from one JSON source of truth.",
    language: "Rust",
    stars: 812,
    forks: 44,
    updatedAt: "2026-01-19T09:00:00Z",
  },
  {
    name: "starter-portfolio",
    description: "An opinionated starting point for a personal site — MDX writing, OG images and a tiny CMS.",
    language: "Astro",
    stars: 1530,
    forks: 402,
    updatedAt: "2025-11-04T09:00:00Z",
    badge: "template",
  },
  {
    name: "grid-lab",
    description: "Experiments with subgrid, container queries and fluid type. No longer maintained.",
    language: "CSS",
    stars: 96,
    forks: 7,
    updatedAt: "2024-05-14T09:00:00Z",
    badge: "archived",
  },
]

export default function RepoCardGrid() {
  return (
    <div className="mx-auto grid max-w-4xl gap-4 sm:grid-cols-2 md:gap-6">
      {repos.map((repo) => (
        <RepoCard key={repo.name} owner="example" href={`#${repo.name}`} now="2026-03-02T09:00:00Z" {...repo} />
      ))}
    </div>
  )
}
```

### Compact

Every detail is optional. Drop the owner, topics and dates for a slim list in a sidebar or bento tile.

```tsx
import { RepoCard } from "@/components/portfolio/repo-card"

const repos = [
  { name: "dotfiles", description: "Shell, editor and terminal config.", language: "Shell", stars: 212 },
  { name: "type-scale", description: "Fluid type scales from two breakpoints.", language: "TypeScript", stars: 1840 },
  { name: "oklab-mixer", description: "Pick and mix colors in perceptual space.", language: "Svelte", stars: 367 },
]

export default function RepoCardCompact() {
  return (
    <ul role="list" aria-label="Side projects" className="flex w-full max-w-sm flex-col gap-3">
      {repos.map((repo) => (
        <li key={repo.name}>
          <RepoCard href={`#${repo.name}`} className="gap-2 p-4 md:p-4" {...repo} />
        </li>
      ))}
    </ul>
  )
}
```

## API Reference

### RepoLanguage

A language name with its colored dot, as on GitHub.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Language name, e.g. "TypeScript". Common languages get GitHub's color automatically. |
| `color` | `string` | — | Dot color for languages not in `languageColors` (any CSS color). |

Also accepts every `span` prop.

### RepoCard

A pinned repository, GitHub style. Every field but `name` is optional, so it also works as a
slim card for side projects. Pass data from the GitHub API or hard-code it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Repository name. |
| `owner` | `string` | — | User or organisation, shown muted before the name ("owner/name"). |
| `description` | `React.ReactNode` | — | A sentence or two, shown in full. Add `[&_[data-slot=repo-card-description]]:line-clamp-2` to the card's `className` to clamp it. |
| `language` | `string` | — | Primary language, shown with its GitHub color dot. |
| `languageColor` | `string` | — | Override the language dot color. |
| `stars` | `number` | — | Star count, shown compact ("4.1K"); the exact number is in the tooltip and read to screen readers. |
| `forks` | `number` | — | Fork count, shown compact like `stars`. |
| `updatedAt` | `Date \| string` | — | Last update, `Date` or ISO string. Shown relative to `now` ("Updated 3 days ago"), or as a date ("Updated Feb 27, 2026") when `now` is not set. |
| `now` | `Date \| string` | — | Reference date for the relative update time, usually the time the page was built or fetched. Without it the card shows the date itself, so server and browser always render the same text. |
| `topics` | `string[]` | — | GitHub topics, shown as small chips. |
| `badge` | `"archived" \| "template" \| "fork"` | — | Status chip next to the name. |
| `href` | `string` | — | Link for the whole card. Defaults to `https://github.com/{owner}/{name}` when `owner` is set. |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the repository name, to fit the page outline. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text appended to the name when the link opens in a new tab. Translate it here. |
| `labels` | `Partial<RepoCardLabels>` | — | Override the built-in English texts: `stars`, `forks` (screen-reader prefixes and tooltips), `updated`, `topics` (list name) and the badges `archived`, `template`, `fork`. E.g. `{ updated: "Aktualisiert" }`. |

Also accepts every `article` prop.

### type RepoCardLabels

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `stars` (required) | `string` | — | Screen-reader prefix and tooltip for the star count: "Stars: 4,120". |
| `forks` (required) | `string` | — | Screen-reader prefix and tooltip for the fork count. |
| `updated` (required) | `string` | — | Text before the update time: "Updated 3 days ago". |
| `topics` (required) | `string` | — | Accessible name of the topics list. |
| `archived` (required) | `string` | — | Badge texts. |
| `template` (required) | `string` | — |  |
| `fork` (required) | `string` | — |  |

## Used in templates

- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)



---

# Resume Link

> Download-your-CV link as a button with a bouncing download icon, or a file card with type, size and last-updated date.

Category: Contact · Registry item: `@portfolio-kit/resume-link` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/resume-link) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/resume-link.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/resume-link
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/resume-link.tsx` and the kit items it uses: `format`, `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

shadcn/ui primitives: `button`.

## Usage

```tsx
import { ResumeLink, resumeLinkVariants } from "@/components/portfolio/resume-link"
```

## Examples

### Demo

A download button for your CV with the file facts beside the label, and a download arrow that bounces on hover.

```tsx
import { ResumeLink } from "@/components/portfolio/resume-link"

export default function ResumeLinkDemo() {
  return (
    <div className="flex max-w-xs flex-col items-start gap-4">
      <p className="text-pretty text-muted-foreground">
        Nine years across product design and front-end engineering. The full story is in my CV.
      </p>
      <ResumeLink href="/files/noa-vale-cv.pdf" fileName="noa-vale-cv.pdf" meta="PDF · 186 KB" />
    </div>
  )
}
```

### Card

`variant="card"` shows the file as a tile with its type, size and last-updated date.

```tsx
import { ResumeLink } from "@/components/portfolio/resume-link"

export default function ResumeLinkCard() {
  return (
    <ResumeLink
      variant="card"
      href="/files/noa-vale-cv.pdf"
      fileName="noa-vale-cv.pdf"
      label="Curriculum vitae"
      meta="PDF · 186 KB"
      updated="2025-09-12"
      className="w-full max-w-md"
    />
  )
}
```

### Documents

A stack of cards: a CV download, a portfolio deck, and a hosted page that opens in a new tab with `view`.

```tsx
import { cn } from "@/lib/utils"
import { ResumeLink } from "@/components/portfolio/resume-link"
import { typography } from "@/lib/typography"

export default function ResumeLinkDocuments() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <h2 className={cn(typography.eyebrow, "mb-1")}>Documents</h2>
      <ResumeLink
        variant="card"
        href="/files/noa-vale-cv.pdf"
        fileName="noa-vale-cv.pdf"
        label="Curriculum vitae"
        meta="PDF · 186 KB"
        updated="2025-09-12"
      />
      <ResumeLink
        variant="card"
        href="/files/portfolio-deck.pdf"
        fileName="portfolio-deck.pdf"
        label="Portfolio deck — selected case studies 2019–2025"
        meta="PDF · 12.4 MB"
        updated="2025-06-02"
      />
      <ResumeLink
        variant="card"
        view
        href="https://example.com/cv"
        fileType="WEB"
        label="Read my CV online"
        meta="Web · 4 min read"
      />
    </div>
  )
}
```

### Tones

`tone` maps to your button styles: primary when the CV is the main ask, outline or ghost next to other actions. Add `view` to open a hosted page in a new tab instead of downloading.

```tsx
import { ResumeLink } from "@/components/portfolio/resume-link"

export default function ResumeLinkTones() {
  return (
    <div className="flex flex-col items-center gap-6">
      <div className="flex flex-wrap items-center justify-center gap-3">
        <ResumeLink tone="default" href="/files/noa-vale-cv.pdf" fileName="noa-vale-cv.pdf" />
        <ResumeLink tone="ghost" view href="https://cv.example.com" label="Read online" />
      </div>
      <div className="flex flex-wrap items-center justify-center gap-3">
        <ResumeLink tone="outline" href="/files/noa-vale-cv.pdf" fileName="noa-vale-cv.pdf" label="Résumé" meta="PDF" />
        <ResumeLink tone="secondary" href="/files/noa-vale-cv.pdf" fileName="noa-vale-cv.pdf" label="Résumé" meta="186 KB" />
      </div>
    </div>
  )
}
```

## API Reference

### ResumeLink

A link to your CV. `variant="button"` sits in a row of actions; `variant="card"` shows the file as a tile with its
type, size and last-updated date.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` (required) | `string` | — | URL of the file (or of a hosted résumé page when `view`). Same-origin files download; browsers open cross-origin ones instead. |
| `variant` | `"button" \| "card" \| null` | `"button"` | `button` for a row of actions, `card` for a file tile with type, size and date. |
| `fileName` | `string` | — | Suggested file name for the download (sets the `download` attribute). |
| `label` | `React.ReactNode` | — | Visible label. Defaults to "Download CV" (button), "View CV" (button + `view`) or the file name (card). |
| `meta` | `React.ReactNode` | — | Short file facts, e.g. "PDF · 186 KB". Part of the link's accessible name, in parentheses: "Download CV (PDF · 186 KB)". Without it, the file type is announced instead. |
| `updated` | `Date \| string` | — | Last updated date, shown on the card as "Updated Sep 2025". |
| `fileType` | `string` | — | Badge on the card's file tile, e.g. `"PDF"` or `"WEB"`. Defaults to the extension of `fileName` or `href`. |
| `tone` | `"default" \| "outline" \| "secondary" \| "ghost"` | `"outline"` | Button style (button variant only). |
| `view` | `boolean` | `false` | Open in a new tab instead of downloading, e.g. for a hosted résumé page or a PDF you'd rather preview. |
| `updatedLabel` | `string` | `"Updated"` | Word before the card's date ("Updated Sep 2025"). |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text for `view` links, which open in a new tab. |

Also accepts every `a` prop.



---

# Reveal

> Fades, lifts and un-blurs elements as they scroll into view, one by one or staggered across a group. Respects reduced motion.

Category: Effects · Registry item: `@portfolio-kit/reveal` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/reveal) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/reveal.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/reveal
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/reveal.tsx` and the kit items it uses: `use-composed-refs`, `use-in-view`, `use-mount-check`, `use-reduced-motion`.

npm dependencies: `radix-ui`.

## Usage

```tsx
import { Reveal, RevealGroup } from "@/components/portfolio/reveal"

<RevealGroup stagger={100} className="grid gap-4 sm:grid-cols-3">
  <Reveal>
    <p>Nine years between design and code.</p>
  </Reveal>
  <Reveal>
    <p>Sixty projects shipped.</p>
  </Reveal>
</RevealGroup>
```

## Examples

### Demo

An intro choreographed with `Reveal` delays: eyebrow, headline and lead, then a slow `RevealGroup` of covers that fade, lift and de-blur one after another. Further down, sections reveal as they scroll into view.

```tsx
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Reveal, RevealGroup } from "@/components/portfolio/reveal"
import {
  Section,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

const projects = [
  { slug: "lumen", title: "Lumen" },
  { slug: "tidewater", title: "Tidewater" },
  { slug: "fieldnote", title: "Fieldnote" },
]

const stats = [
  { value: "9", label: "Years shipping product" },
  { value: "40+", label: "Launches" },
  { value: "11", label: "Teams on one design system" },
]

export default function RevealDemo() {
  return (
    <main>
      <Section spacing="sm" className="pt-12 md:pt-16">
        <Reveal>
          <p className={typography.eyebrow}>Design Engineer · Lisbon</p>
        </Reveal>
        <Reveal delay={150}>
          <h1 className={cn(typography.display, "mt-6 max-w-4xl")}>Things worth making slowly.</h1>
        </Reveal>
        <RevealGroup delay={700} stagger={600} duration={1000} className="mt-10 grid grid-cols-3 gap-3 md:gap-4">
          {projects.map((project) => (
            <a
              key={project.slug}
              href={`#${project.slug}`}
              aria-label={project.title}
              className="block aspect-[4/3] overflow-hidden rounded-xl border outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
            >
              <GenerativeArt seed={project.slug} variant="interface" />
            </a>
          ))}
        </RevealGroup>
      </Section>

      <Section divider>
        <Reveal>
          <SectionHeader>
            <SectionEyebrow index={1}>About</SectionEyebrow>
            <SectionTitle>Nine years between design and code.</SectionTitle>
            <SectionDescription>
              I help startups and studios turn rough ideas into interfaces that feel inevitable — from the first
              sketch to the last pull request.
            </SectionDescription>
          </SectionHeader>
        </Reveal>
        <RevealGroup stagger={100} className="mt-12 grid gap-4 sm:grid-cols-3">
          {stats.map((stat) => (
            <div key={stat.label} className="flex flex-col gap-2 rounded-2xl border bg-card p-5 shadow-card md:p-6">
              <span className="font-heading text-4xl md:text-5xl">{stat.value}</span>
              <span className={typography.body}>{stat.label}</span>
            </div>
          ))}
        </RevealGroup>
      </Section>
    </main>
  )
}
```

### Staggered group

`RevealGroup` reveals its direct children one after another without adding wrappers, so it drops straight into a grid.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { RevealGroup } from "@/components/portfolio/reveal"
import { typography } from "@/lib/typography"

const projects = [
  { slug: "lumen", title: "Lumen", client: "Halcyon Labs" },
  { slug: "tidewater", title: "Tidewater", client: "Tidewater Energy" },
  { slug: "fieldnote", title: "Fieldnote", client: "Fieldnote Inc." },
] as const

export default function RevealStagger() {
  return (
    <RevealGroup stagger={120} className="mx-auto grid max-w-5xl gap-4 sm:grid-cols-3">
      {projects.map((project) => (
        <a
          key={project.slug}
          href={`#${project.slug}`}
          className="group flex flex-col overflow-hidden rounded-2xl border bg-card shadow-card outline-none transition-colors duration-300 ease-smooth hover:border-border-hover focus-visible:ring-[3px] focus-visible:ring-ring/50"
        >
          <span className="block aspect-[4/3] overflow-hidden border-b">
            <GenerativeArt
              seed={project.slug}
              variant="interface"
              className="transition-transform duration-700 ease-smooth motion-reduce:transition-none [@media(hover:hover)]:group-hover:scale-[1.04]"
            />
          </span>
          <span className="flex flex-col gap-1 p-5">
            <span className={typography.meta}>{project.client}</span>
            <span className={typography.heading}>{project.title}</span>
          </span>
        </a>
      ))}
    </RevealGroup>
  )
}
```

### Directions

Alternate `from="left"` and `from="right"` down a process list; `repeat` replays each step whenever it re-enters the view. Scroll the preview.

```tsx
import { cn } from "@/lib/utils"
import { Reveal } from "@/components/portfolio/reveal"
import { Section } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

const steps = [
  { title: "Research", body: "Interviews, analytics and a teardown of what exists — a week, not a quarter." },
  { title: "Design", body: "Flows and prototypes in real code, so the debate is about the thing itself." },
  { title: "Build", body: "Accessible, typed components the team can own after I leave." },
  { title: "Refine", body: "Ship, measure, sand down the rough edges. Repeat." },
]

export default function RevealDirections() {
  return (
    <Section size="sm">
      <p className={typography.meta}>Scroll down ↓</p>
      <ol role="list" className="mt-[40vh] mb-[30vh] flex flex-col gap-32">
        {steps.map((step, i) => (
          <li key={step.title} className={cn("flex", i % 2 ? "justify-end text-right" : "justify-start")}>
            <Reveal from={i % 2 ? "left" : "right"} repeat className="flex max-w-sm flex-col gap-3">
              <span className={cn(typography.meta, "text-highlight-ink")}>{String(i + 1).padStart(2, "0")}</span>
              <h2 className={typography.title}>{step.title}</h2>
              <p className={typography.body}>{step.body}</p>
            </Reveal>
          </li>
        ))}
      </ol>
    </Section>
  )
}
```

## API Reference

### Reveal

Fades, lifts and de-blurs its content the first time it scrolls into view (or, for a short
element at the very end of the page, once it is wholly visible). Content is never hidden for
good: without `IntersectionObserver` it shows immediately, with reduced motion it never
animates, it always prints, and server-rendered HTML reveals itself after two seconds even if
JavaScript never runs.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `"up" \| "down" \| "left" \| "right" \| "none"` | `"up"` | Direction of travel: `up` starts below and rises into place, `left` slides in from the right. `none` only fades. |
| `delay` | `number` | `0` | Delay before the entrance starts, in ms. Useful to sequence a few siblings (`0`, `120`, `240`…). |
| `duration` | `number` | `800` | Duration of the entrance, in ms. |
| `blur` | `boolean` | `true` | Add a slight blur that clears as the element settles. |
| `repeat` | `boolean` | `false` | Hide again when the element leaves the viewport, and replay the entrance when it comes back. |
| `asChild` | `boolean` | — | Merge onto the single child instead of wrapping it in a `<div>`. Keeps grids, lists and flex rows intact. |

Also accepts every `div` prop.

### RevealGroup

Reveals each direct child in sequence. No wrappers are inserted, so it works
inside grids, lists and flex rows: the group itself is the grid. The whole group is observed
once, so every child starts when the group scrolls into view; split a very tall group into
several groups if its last rows should wait for the reader.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stagger` | `number` | `80` | Delay between each direct child, in ms. |
| `delay` | `number` | `0` | Delay before the first child, in ms. |
| `duration` | `number` | `700` | Duration of each child's entrance, in ms. |
| `from` | `"up" \| "down" \| "left" \| "right" \| "none"` | `"up"` | Direction every child travels from. See `Reveal`. |
| `blur` | `boolean` | `true` | Add a slight blur that clears as each child settles. |
| `repeat` | `boolean` | `false` | Hide the children again when the group leaves the viewport, and replay the sequence when it comes back. |
| `asChild` | `boolean` | — | Merge onto the single child element (e.g. your own `<ul>`) instead of rendering a `<div>`. |

Also accepts every `div` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)
- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md)
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Scramble Text

> Text that decodes from random glyphs, left to right, on mount, when it scrolls into view or on hover. The layout never shifts.

Category: Effects · Registry item: `@portfolio-kit/scramble-text` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/scramble-text) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/scramble-text.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/scramble-text
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/scramble-text.tsx` and the kit items it uses: `use-in-view`, `use-reduced-motion`.

## Usage

```tsx
import { ScrambleText } from "@/components/portfolio/scramble-text"
```

## Examples

### Demo

A hero title that decodes left to right on load and again whenever the pointer comes back to it. Every glyph sits in a fixed cell, so the layout never shifts.

```tsx
import { cn } from "@/lib/utils"
import { ScrambleText } from "@/components/portfolio/scramble-text"
import { typography } from "@/lib/typography"

export default function ScrambleTextDemo() {
  return (
    <div className="mx-auto flex max-w-4xl flex-col gap-6 py-12 md:py-20">
      <ScrambleText as="p" trigger="mount" duration={1200} className={typography.eyebrow}>
        Portfolio 2019 — 2025
      </ScrambleText>
      <ScrambleText
        as="h1"
        trigger={["mount", "hover"]}
        delay={150}
        duration={1100}
        className={typography.display}
      >
        Design Engineer
      </ScrambleText>
      <p className={cn(typography.lead, "max-w-md")}>
        I design and build calm, fast interfaces for ambitious product teams.
      </p>
    </div>
  )
}
```

### On hover

`trigger="hover"` replays the decode on pointer enter or keyboard focus. The link width stays fixed, so it suits mono nav links.

```tsx
import { ScrambleText } from "@/components/portfolio/scramble-text"
import { typography } from "@/lib/typography"

const links = [
  { label: "Work", href: "#work" },
  { label: "About", href: "#about" },
  { label: "Writing", href: "#writing" },
  { label: "Contact", href: "#contact" },
]

export default function ScrambleTextHover() {
  return (
    <div className="flex flex-col items-center gap-8">
      <nav aria-label="Primary">
        <ul role="list" className="flex flex-wrap justify-center gap-x-8 gap-y-3">
          {links.map((link) => (
            <li key={link.href}>
              <a
                href={link.href}
                className="inline-flex min-h-6 items-center rounded-sm font-mono text-sm tracking-[0.16em] uppercase outline-none transition-colors duration-200 hover:text-highlight-ink focus-visible:ring-[3px] focus-visible:ring-ring/50"
              >
                <ScrambleText trigger="hover" duration={500}>
                  {link.label}
                </ScrambleText>
              </a>
            </li>
          ))}
        </ul>
      </nav>
      <p className={typography.meta}>Hover or tab through the links</p>
    </div>
  )
}
```

### Status lines

Stagger `delay` across a few mono lines for a boot-log intro, here on a panel forced to the dark palette.

```tsx
import { cn } from "@/lib/utils"
import { StatusDot } from "@/components/portfolio/availability-badge"
import { ScrambleText } from "@/components/portfolio/scramble-text"
import { typography } from "@/lib/typography"

const lines = [
  { key: "Name", value: "Noa Vale" },
  { key: "Role", value: "Design Engineer" },
  { key: "Based", value: "Lisbon, UTC+0" },
  { key: "Status", value: "Open to new work" },
]

export default function ScrambleTextStatusLines() {
  return (
    <div className="dark w-full max-w-md rounded-2xl border bg-background p-5 text-foreground shadow-card md:p-6">
      <div className="flex items-center justify-between gap-4 border-b pb-4">
        <span className={typography.eyebrow}>whoami</span>
        <StatusDot />
      </div>
      <dl className="mt-4 flex flex-col gap-2.5 font-mono text-sm">
        {lines.map((line, i) => (
          <div key={line.key} className="grid grid-cols-[5rem_1fr] gap-4">
            <dt className="text-muted-foreground">{line.key}</dt>
            <dd>
              <ScrambleText
                trigger="mount"
                delay={i * 220}
                duration={700}
                className={cn(i === lines.length - 1 && "text-highlight-ink")}
              >
                {line.value}
              </ScrambleText>
            </dd>
          </div>
        ))}
      </dl>
    </div>
  )
}
```

## API Reference

### ScrambleText

Decodes a string left to right. Every character is a fixed cell: an invisible copy of the
final glyph holds the width and the visible glyph is painted on top, so nothing jitters or
reflows. The server renders the final text (random glyphs only appear after hydration), assistive
tech reads the real text once from a visually hidden copy, with reduced motion the text never
scrambles, and printing always shows the final text (even mid-decode or before a `view` run).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `string` | — | The final text. Screen readers and copy-paste always get this, never the scrambled glyphs. |
| `as` | `"span" \| "p" \| "h1" \| "h2" \| "h3" \| "h4" \| "div"` | `"span"` | Element to render — pick the right heading level for the page outline. A `span` is `inline-block`. |
| `trigger` | `"mount" \| "view" \| "hover" \| ("mount" \| "view" \| "hover")[]` | `"view"` | What starts the effect: `mount` plays once after load, `view` once when the text first scrolls into view, `hover` on every pointer enter or keyboard focus (of the text, or of the link or button around it). Combine with an array, e.g. `["view", "hover"]`. Each run ends after `delay` + `duration`. |
| `duration` | `number` | `900` | Total time until the last character resolves, in ms. |
| `delay` | `number` | `0` | Delay before starting, in ms (mount / view only). |
| `speed` | `number` | `45` | How often a scrambling glyph changes, in ms. Lower is noisier. |
| `characters` | `string` | `"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789#%&*+=/<>"` | Glyph pool used while scrambling. Case follows the final character. |

Also accepts every `span` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Not Found](https://www.parthjadhav.com/products/portfolio-kit/templates/not-found.md)



---

# Scroll Cue

> “Scroll” indicator for full-height heroes: a moving line, a mouse with a rolling wheel or a bobbing arrow. Can link to the next section.

Category: Hero · Registry item: `@portfolio-kit/scroll-cue` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-cue) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/scroll-cue.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/scroll-cue
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/scroll-cue.tsx`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import { ScrollCue, scrollCueVariants } from "@/components/portfolio/scroll-cue"
```

## Examples

### Demo

Anchored to the bottom of a full-height hero, it hints there's more below and jumps to the next section when clicked.

```tsx
import { ScrollCue } from "@/components/portfolio/scroll-cue"
import { Section, SectionEyebrow, SectionHeader, SectionTitle } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

export default function ScrollCueDemo() {
  return (
    <>
      <header className="relative flex min-h-svh flex-col items-center justify-center gap-4 border-b px-6 pb-24 text-center">
        <h1 className="font-heading text-4xl text-balance sm:text-5xl md:text-6xl">Calm, fast interfaces.</h1>
        <p className={typography.lead}>Design engineer in Lisbon.</p>
        <ScrollCue
          href="#work"
          variant="mouse"
          aria-label="Scroll to selected work"
          className="absolute bottom-[max(2rem,env(safe-area-inset-bottom))] left-1/2 -translate-x-1/2"
        />
      </header>
      <Section id="work">
        <SectionHeader>
          <SectionEyebrow index={1}>Selected work</SectionEyebrow>
          <SectionTitle>Things I&rsquo;ve shipped lately</SectionTitle>
        </SectionHeader>
      </Section>
    </>
  )
}
```

### Variants

A travelling line, a mouse with a rolling wheel or a bobbing arrow, stacked under the label or inline beside it.

```tsx
import { ScrollCue } from "@/components/portfolio/scroll-cue"

export default function ScrollCueVariants() {
  return (
    <div className="flex flex-col items-center gap-14">
      <div className="flex items-start gap-14">
        <ScrollCue href="#work" variant="line" />
        <ScrollCue href="#work" variant="mouse" />
        <ScrollCue href="#work" variant="arrow" />
      </div>
      <div className="flex flex-col items-start gap-5">
        <ScrollCue href="#work" layout="inline" variant="line" label="Scroll to explore" />
        <ScrollCue href="#work" layout="inline" variant="mouse" />
        <ScrollCue href="#work" layout="inline" variant="arrow" label="Selected work" />
      </div>
    </div>
  )
}
```

### On Media

`tone="on-media"` stays white over photos and video in every theme and mode. Without `href` the cue is purely decorative.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { ScrollCue } from "@/components/portfolio/scroll-cue"

export default function ScrollCueOnMedia() {
  return (
    <div className="relative isolate mx-auto flex aspect-[4/5] max-w-4xl flex-col justify-end overflow-hidden rounded-2xl sm:aspect-video">
      <GenerativeArt seed="coast-field-notes" variant="landscape" className="absolute inset-0 -z-10" />
      <div aria-hidden className="absolute inset-0 -z-10 bg-gradient-to-t from-black/70 via-black/20 to-transparent" />
      <div className="flex items-end justify-between gap-6 p-6 md:p-8">
        <p className="max-w-xs font-heading text-3xl leading-tight text-white md:text-4xl">Field notes from the coast</p>
        <ScrollCue tone="on-media" variant="mouse" href="#story" label="Read" aria-label="Read the story" />
      </div>
    </div>
  )
}
```

## API Reference

### ScrollCue

Animated "scroll" hint. A link when `href` is set (keyboard reachable, hover and focus styles);
without it, a decorative element hidden from assistive tech. The animation plays for about four
seconds and then rests, is static under reduced motion, and the cue is hidden when printed.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | Target to scroll to, e.g. "#work". Without it the cue is decorative and hidden from assistive tech. |
| `variant` | `"line" \| "mouse" \| "arrow"` | `"line"` | The indicator: a travelling `line`, a `mouse` with a rolling wheel, or a bobbing `arrow` in a circle. |
| `layout` | `"stack" \| "inline"` | `"stack"` | `stack` puts the indicator under the label (centered hero bottoms); `inline` sits beside it (meta rows). |
| `tone` | `"default" \| "on-media"` | `"default"` | `on-media` is white on photos and video, in any theme or mode. |
| `label` | `string` | `"Scroll"` | Visible (or screen-reader) label. With `href` it names the link; pass `aria-label` for a fuller name that starts with it, e.g. "Scroll to selected work". |
| `hideLabel` | `boolean` | `false` | Keep the label for screen readers only. |

Also accepts every `a` prop.



---

# Scroll Progress

> Reading-progress indicator for the page or a single article, as a thin bar across the top or a small ring with a percentage.

Category: Navigation · Registry item: `@portfolio-kit/scroll-progress` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-progress) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/scroll-progress.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/scroll-progress
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/scroll-progress.tsx` and the kit items it uses: `use-composed-refs`, `use-scroll-progress`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { ScrollProgress, scrollProgressVariants } from "@/components/portfolio/scroll-progress"
```

## Examples

### Demo

A thin reading bar pinned to the top of the page.

```tsx
import { ScrollProgress } from "@/components/portfolio/scroll-progress"
import { typography } from "@/lib/typography"

const paragraphs = [
  "Every product team eventually builds the same button twice. Then three times. By the time there are eleven, nobody remembers which one is right — and every review becomes an argument about padding.",
  "A design system is usually pitched as a way to move faster. In practice, its first job is to make disagreements cheap: one place to decide, one place to change, and a shared vocabulary for everything in between.",
  "We started with tokens rather than components. Colors, spacing and type became an API with names, owners and a changelog. Components came later, and only once three teams had asked for the same thing.",
  "The hardest part wasn't the code. It was deciding what not to build — saying no to the one-off date picker so that the shared one could be great, and trusting teams to compose the rest.",
  "Two years in, the system powers eleven products. New screens take days instead of weeks, and the arguments are about the product again, not the padding.",
  "If there's a lesson, it's that consistency is a side effect. Make the right thing the easy thing, and teams will choose it without being asked.",
  "The rest is maintenance: pruning what nobody uses, documenting what everybody does, and listening for the next button that's about to be built twice.",
]

export default function ScrollProgressDemo() {
  return (
    <>
      <ScrollProgress thickness={3} />
      <article className="mx-auto flex max-w-2xl flex-col gap-6 px-5 py-16 sm:px-6 md:py-20">
        <p className={typography.eyebrow}>Essay · 6 min read</p>
        <h1 className={typography.title}>Design systems are a way to make disagreements cheap</h1>
        {paragraphs.map((text) => (
          <p key={text} className={typography.lead}>
            {text}
          </p>
        ))}
      </article>
    </>
  )
}
```

### Ring

A small floating ring with the percentage inside, for long reads where a bar would clash with a sticky header.

```tsx
import { ScrollProgress } from "@/components/portfolio/scroll-progress"
import { typography } from "@/lib/typography"

const chapters = [
  {
    title: "Listening first",
    body: [
      "We spent the first three weeks in interviews with every product team. Each had solved buttons, forms and empty states in slightly different ways — and every difference cost time in review.",
      "Support tickets told the same story from the other side. Customers noticed the inconsistencies long before the teams had a name for them.",
    ],
  },
  {
    title: "Tokens as an API",
    body: [
      "Colors, spacing and type became named, versioned decisions with owners and a changelog. Teams could depend on them the way they depend on any other package.",
      "Breaking changes got a major version and a migration note. Nobody had to upgrade on the system team's schedule — only on their own.",
    ],
  },
  {
    title: "Components, reluctantly",
    body: [
      "A component entered the system only once three teams had asked for it. That rule kept the library small, and made every piece in it genuinely shared.",
      "The one-off date picker never made it in. Saying no to it is why the shared one is good enough that nobody asks for another.",
    ],
  },
  {
    title: "What changed",
    body: [
      "Eleven products now ship from one foundation. New screens take days instead of weeks, and design reviews are about the product again rather than the padding.",
      "The system team now spends its time on new problems — motion, data density, accessibility audits — instead of old buttons.",
    ],
  },
]

export default function ScrollProgressRing() {
  return (
    <>
      <article className="mx-auto flex max-w-2xl flex-col gap-12 px-5 py-16 sm:px-6 md:py-20">
        <header className="flex flex-col gap-4">
          <p className={typography.eyebrow}>Case study · Lumen</p>
          <h1 className={typography.title}>Building a design system eleven teams actually use</h1>
        </header>
        {chapters.map((chapter, i) => (
          <section key={chapter.title} className="flex flex-col gap-4">
            <p className={typography.meta}>{String(i + 1).padStart(2, "0")}</p>
            <h2 className="font-heading text-2xl leading-tight md:text-3xl">{chapter.title}</h2>
            {chapter.body.map((text) => (
              <p key={text} className={typography.lead}>
                {text}
              </p>
            ))}
          </section>
        ))}
      </article>
      <ScrollProgress variant="ring" showValue />
    </>
  )
}
```

### Article Only

Pass `targetRef` to measure one article instead of the whole page. The bar stays empty through the intro and is full when the article ends.

```tsx
import * as React from "react"

import { ScrollProgress } from "@/components/portfolio/scroll-progress"
import { typography } from "@/lib/typography"

const paragraphs = [
  "Motion is a promise. When a panel slides in from the right, you expect it to leave the same way — and when it doesn't, the interface feels subtly untrustworthy.",
  "The best transitions are the ones nobody notices. They explain where something came from, where it went, and then they get out of the way. Anything longer than 300 milliseconds starts to feel like waiting.",
  "Easing matters more than duration. An expo-out curve front-loads the movement, so the element is almost in place before the eye catches up — fast, but never abrupt.",
  "And everything that moves should also be able to stand still. Respecting reduced motion isn't an edge case; it's a second design with the same care as the first.",
  "Start with the smallest possible movement: a fade, a few pixels of travel. Add more only when the user would otherwise lose track of something.",
  "Then watch someone use it. If they comment on the animation, it's probably too much. If they never notice it but always know where they are, it's right.",
]

export default function ScrollProgressArticle() {
  const articleRef = React.useRef<HTMLElement>(null)

  return (
    <>
      <ScrollProgress targetRef={articleRef} thickness={3} label="Article progress" />
      <header className="border-b bg-muted/50">
        <div className="mx-auto flex max-w-2xl flex-col gap-4 px-5 py-16 sm:px-6">
          <p className={typography.eyebrow}>Writing · Mar 2025</p>
          <h1 className={typography.title}>Motion that explains itself</h1>
          <p className={typography.lead}>The bar starts filling when the article does — not at the top of the page.</p>
        </div>
      </header>
      <article ref={articleRef} className="mx-auto flex max-w-2xl flex-col gap-6 px-5 py-14 sm:px-6">
        {paragraphs.map((text) => (
          <p key={text} className={typography.lead}>
            {text}
          </p>
        ))}
      </article>
      <footer className="border-t bg-muted/50">
        <div className="mx-auto flex max-w-2xl flex-col gap-2 px-5 py-16 sm:px-6">
          <p className={typography.eyebrow}>Keep reading</p>
          <p className="font-heading text-2xl">Tokens are an API, not a palette</p>
        </div>
      </footer>
    </>
  )
}
```

### Static Values

`position="static"` with a `value` turns it into a plain progress meter — for chapter lists, reading queues and course progress.

```tsx
import { ScrollProgress } from "@/components/portfolio/scroll-progress"
import { typography } from "@/lib/typography"

const queue = [
  { title: "Motion that explains itself", minutes: "6 min", progress: 1 },
  { title: "Tokens are an API, not a palette", minutes: "9 min", progress: 0.48 },
  { title: "The case for boring navigation", minutes: "4 min", progress: 0.12 },
]

export default function ScrollProgressStatic() {
  return (
    <section className="flex w-full max-w-sm flex-col gap-5 rounded-2xl border bg-card p-5 text-card-foreground shadow-card md:p-6">
      <div className="flex items-center justify-between gap-4">
        <h2 className={typography.heading}>Reading queue</h2>
        <ScrollProgress variant="ring" position="static" value={0.53} showValue label="Queue progress" />
      </div>
      <ul role="list" className="flex flex-col gap-5">
        {queue.map((post) => (
          <li key={post.title} className="flex flex-col gap-2.5">
            <div className="flex items-baseline justify-between gap-4">
              <span className="truncate text-sm font-medium">{post.title}</span>
              <span className={`${typography.meta} shrink-0`}>
                {post.progress === 1 ? "Done" : `${Math.round(post.progress * 100)}%`}
              </span>
            </div>
            <ScrollProgress position="static" value={post.progress} thickness={3} label={`${post.title} — ${post.minutes}`} />
          </li>
        ))}
      </ul>
    </section>
  )
}
```

## API Reference

### ScrollProgress

A reading indicator that fills as the reader scrolls. Progress is painted straight to the DOM on
animation frames (no React re-renders) and snaps without easing under reduced motion.

While it tracks scrolling it is decorative (`aria-hidden`): the browser's scroll position already
tells assistive technology where the reader is, and a progressbar that changes on every scroll would
be noise. With `value` it is a `progressbar` named by `label`, for meters that carry information.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"bar" \| "ring" \| null` | `"bar"` | `bar`: a hairline across the top of the viewport. `ring`: a small floating ring (optionally with the percentage) in the corner `BackToTop` uses, so pick one or move the other. |
| `position` | `"fixed" \| "static" \| null` | `"fixed"` | `fixed` pins the bar to the top edge (the ring to the bottom-right corner) and hides it in print. Under a sticky site header, move the bar below it with a `className` such as `top-16`, or render it `static` inside the header (`absolute inset-x-0 bottom-0`). `static` renders it in place; combine it with `value` for a plain progress meter. |
| `targetRef` | `React.RefObject<HTMLElement \| null>` | — | Track progress through this element (e.g. an `<article>`) instead of the whole page: empty until its top reaches the top of the viewport, full when its bottom reaches the bottom of the viewport. |
| `value` | `number` | — | Drive the indicator yourself (0–1). Disables scroll tracking and makes it a named `progressbar`. |
| `thickness` | `2 \| 3 \| 4` | `2` | Bar height in px. |
| `showValue` | `boolean` | `false` | Show the percentage inside the ring. |
| `label` | `string` | `"Reading progress"` | Accessible name of the `progressbar` when `value` is set. |

Also accepts every `div` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)



---

# Scroll Steps

> Scrollytelling for case studies and process write-ups: steps of text scroll past a sticky media panel that cross-fades to the active step's image.

Category: Work · Registry item: `@portfolio-kit/scroll-steps` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-steps) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/scroll-steps.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/scroll-steps
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/scroll-steps.tsx` and the kit items it uses: `typography`, `use-composed-refs`, `use-scroll-progress`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  ScrollStep,
  ScrollStepDescription,
  ScrollStepTitle,
  ScrollSteps,
} from "@/components/portfolio/scroll-steps"

<ScrollSteps side="right">
  <ScrollStep value="research" media={<img src="/work/research.jpg" alt="Interview notes on a wall" />}>
    <ScrollStepTitle>Research</ScrollStepTitle>
    <ScrollStepDescription>Twelve interviews with night-shift nurses.</ScrollStepDescription>
  </ScrollStep>
  <ScrollStep value="prototype" media={<img src="/work/prototype.jpg" alt="A paper prototype" />}>
    <ScrollStepTitle>Prototype</ScrollStepTitle>
    <ScrollStepDescription>Paper first, then a clickable build on the ward.</ScrollStepDescription>
  </ScrollStep>
</ScrollSteps>
```

## Examples

### Demo

A case study told in four steps: the text scrolls while the screen beside it cross-fades to match. Scroll the preview; on phones each step shows its screen inline.

```tsx
import { DeviceFrame } from "@/components/portfolio/device-frame"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ScrollStep,
  ScrollStepDescription,
  ScrollSteps,
  ScrollStepTitle,
} from "@/components/portfolio/scroll-steps"
import {
  Section,
  SectionContent,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

const steps = [
  {
    value: "audit",
    label: "Audit",
    title: "Four dashboards, one job",
    body: "Operators at Tidewater Energy watched turbines across four tools. We sat with three shifts and mapped every alert they acted on, and the ninety they ignored.",
    url: "tidewater.example.com/audit",
    hue: 195,
  },
  {
    value: "model",
    label: "Model",
    title: "A grid you can read at 3 a.m.",
    body: "Turbines became one map, grouped by feeder line. Colour is saved for things that need a person; everything else stays quiet and grey.",
    url: "tidewater.example.com/map",
    hue: 210,
  },
  {
    value: "alerts",
    label: "Alerts",
    title: "Fewer, better alerts",
    body: "Alerts now arrive with the reading that triggered them, the last similar event and a suggested next step. Acknowledging one takes a single key.",
    url: "tidewater.example.com/alerts",
    hue: 25,
  },
  {
    value: "launch",
    label: "Launch",
    title: "Shipped to 40 wind farms",
    body: "Rolled out over six weeks, farm by farm. Median response time to a critical alert fell from eleven minutes to four.",
    url: "tidewater.example.com/overview",
    hue: 150,
  },
] as const

export default function ScrollStepsDemo() {
  return (
    <Section>
      <SectionHeader>
        <SectionEyebrow index={2}>Process</SectionEyebrow>
        <SectionTitle>From four tools to one calm screen</SectionTitle>
      </SectionHeader>
      <SectionContent>
        <ScrollSteps>
          {steps.map((step, i) => (
            <ScrollStep
              key={step.value}
              value={step.value}
              media={
                <DeviceFrame url={step.url}>
                  <GenerativeArt
                    seed={`tidewater-${step.value}`}
                    variant="interface"
                    hue={step.hue}
                    label={`Tidewater ${step.label.toLowerCase()} screen`}
                  />
                </DeviceFrame>
              }
            >
              <p className={typography.eyebrow}>
                <span className="text-highlight-ink tabular-nums">{String(i + 1).padStart(2, "0")}</span> · {step.label}
              </p>
              <ScrollStepTitle>{step.title}</ScrollStepTitle>
              <ScrollStepDescription>{step.body}</ScrollStepDescription>
            </ScrollStep>
          ))}
        </ScrollSteps>
      </SectionContent>
    </Section>
  )
}
```

### Process

A how-I-work walkthrough with the media on the left: numbered steps with icons beside a phone that swaps screens. Scroll the preview.

```tsx
import { Compass, PenTool, Rocket, TestTube } from "lucide-react"

import { DeviceFrame } from "@/components/portfolio/device-frame"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ScrollStep,
  ScrollStepDescription,
  ScrollSteps,
  ScrollStepTitle,
} from "@/components/portfolio/scroll-steps"
import {
  Section,
  SectionContent,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const stages = [
  {
    title: "Listen",
    body: "A week of interviews and shadowing before any pixels. I leave with the three problems worth solving and the ones we agree to leave alone.",
    icon: Compass,
    hue: 268,
  },
  {
    title: "Sketch",
    body: "Rough flows on paper, then a clickable prototype on your phone by Friday. Cheap to change, real enough to argue about.",
    icon: PenTool,
    hue: 320,
  },
  {
    title: "Test",
    body: "Five people a round, every round recorded. What confuses two of them gets fixed before the next session.",
    icon: TestTube,
    hue: 30,
  },
  {
    title: "Ship",
    body: "Production design in your component library, handed over with notes, and a month of check-ins after launch.",
    icon: Rocket,
    hue: 160,
  },
] as const

export default function ScrollStepsProcess() {
  return (
    <Section>
      <SectionHeader>
        <SectionEyebrow>How I work</SectionEyebrow>
        <SectionTitle>Four steps, one app</SectionTitle>
        <SectionDescription>How a typical eight-week mobile project runs, from the first call to launch.</SectionDescription>
      </SectionHeader>
      <SectionContent>
        <ScrollSteps side="left" mediaClassName="mx-auto w-full max-w-64">
          {stages.map(({ title, body, icon: Icon, hue }, i) => (
            <ScrollStep
              key={title}
              media={
                <DeviceFrame variant="phone" className="max-md:max-w-56">
                  <GenerativeArt seed={`process-${title}`} variant="interface" hue={hue} label={`App screen at the ${title.toLowerCase()} stage`} />
                </DeviceFrame>
              }
            >
              <div className="flex items-center gap-3">
                <span className="flex size-10 items-center justify-center rounded-pill border bg-card text-highlight-ink">
                  <Icon aria-hidden className="size-4.5" />
                </span>
                <span className="font-mono text-xs text-muted-foreground tabular-nums">
                  {String(i + 1).padStart(2, "0")} / {String(stages.length).padStart(2, "0")}
                </span>
              </div>
              <ScrollStepTitle>{title}</ScrollStepTitle>
              <ScrollStepDescription>{body}</ScrollStepDescription>
            </ScrollStep>
          ))}
        </ScrollSteps>
      </SectionContent>
    </Section>
  )
}
```

## API Reference

### ScrollSteps

The two-column scrollytelling layout: an ordered list of `ScrollStep`s beside a sticky panel
showing the active step's media. Below `md`, with reduced motion, in print and without
JavaScript it is a stacked list with each step's media inline.

The panel needs the page to scroll: `position: sticky` stops working inside an ancestor with
`overflow: hidden`, `auto` or `scroll` (a common one is `overflow-x: hidden` on a page wrapper;
use `overflow-x: clip` instead). When keyboard focus moves into a step's content, the page
scrolls that step into place so the panel shows its media. Only the media on screen is exposed
to screen readers (the panel shows one step's), so keep essential information in the step text.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `React.ReactNode` | — | `ScrollStep`s, as direct children (the panel reads each one's `media`). |
| `side` | `"left" \| "right" \| null` | `"right"` | Which side the sticky media panel sits on from `md` up. |
| `value` | `string` | — | The active step (controlled). Shows that step's media whatever the scroll position. |
| `defaultValue` | `string` | — | The step active before the reader scrolls (uncontrolled). Defaults to the first step. |
| `onValueChange` | `(value: string) => void` | — | Called with the step's `value` when scrolling makes another step active. |
| `offset` | `number` | `0.5` | Horizontal line across the viewport, as a fraction from the top, that decides which step is active: the last step whose top has crossed it. `0.5` is the middle of the screen. |
| `top` | `string` | — | Where the stuck media panel sits from the top of the viewport, as any CSS length (clear a fixed header with `"6rem"`). By default it is centred vertically. |
| `mediaClassName` | `string` | — | Classes for the sticky media panel, e.g. a max width or a background behind the media. |

Also accepts every `div` prop.

### ScrollStep

One step (`<li>`). Put a `ScrollStepTitle` and `ScrollStepDescription` (or any content) inside.
Side by side, each step is at least 70% of the viewport tall with its content centred, so one
step is in focus at a time; the active one gets `aria-current="step"` and `data-state="active"`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Identifies the step for `value`/`onValueChange`; unique within the list. Defaults to its zero-based index as a string. |
| `media` | `React.ReactNode` | — | What the sticky panel shows while this step is active, also shown above the step when the layout is stacked: an `<img>`, `<video>`, `<GenerativeArt />` or a `DeviceFrame`. Give images real `alt` text. It renders twice (inline and in the panel) but only the copy on screen is exposed, and an autoplaying `<video>` plays only there. Keep autoplaying video muted, and leave it out under reduced motion. |

Also accepts every `li` prop.

### ScrollStepTitle

The step's heading. Side by side, inactive steps' titles fade to `muted-foreground`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level. Match your page outline. |

Also accepts every `h3` prop.

### ScrollStepDescription

One or two short paragraphs of step copy.

Also accepts every `p` prop.



---

# Scroll Text

> A statement paragraph whose words light up one after another as the reader scrolls through it, tied to scroll position rather than played once.

Category: Effects · Registry item: `@portfolio-kit/scroll-text` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-text) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/scroll-text.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/scroll-text
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/scroll-text.tsx` and the kit items it uses: `use-composed-refs`, `use-isomorphic-layout-effect`, `use-reduced-motion`, `use-scroll-progress`.

## Usage

```tsx
import {
  ScrollText,
  ScrollTextHighlight,
} from "@/components/portfolio/scroll-text"

<ScrollText as="p" offset={[0.9, 0.4]}>
  I design and build calm software for{" "}
  <ScrollTextHighlight>small, ambitious teams</ScrollTextHighlight>.
</ScrollText>
```

## Examples

### Demo

An about statement that fills in word by word as you read down the page, and dims again if you scroll back. Scroll the preview.

```tsx
import { cn } from "@/lib/utils"
import { Section } from "@/components/portfolio/section"
import { ScrollText } from "@/components/portfolio/scroll-text"
import { typography } from "@/lib/typography"

export default function ScrollTextDemo() {
  return (
    <Section>
      <p className={typography.meta}>Scroll down ↓</p>
      <p className={cn(typography.eyebrow, "mt-[30vh]")}>About</p>
      <ScrollText as="h2" className={cn(typography.title, "mt-4 max-w-4xl")}>
        I’m Mara Lind, a product designer in Copenhagen. For eight years I’ve helped small teams turn tangled tools into
        calm, legible software: interfaces that explain themselves, respect people’s time and still feel good on the
        hundredth use.
      </ScrollText>
      <div aria-hidden className="h-[60vh]" />
    </Section>
  )
}
```

### Highlighted words

A studio manifesto that fills character by character from muted to full colour, with the services lighting up in the accent. Unread text stays readable at every point. Scroll the preview.

```tsx
import { cn } from "@/lib/utils"
import { Section } from "@/components/portfolio/section"
import { ScrollText, ScrollTextHighlight } from "@/components/portfolio/scroll-text"
import { typography } from "@/lib/typography"

export default function ScrollTextHighlightExample() {
  return (
    <Section className="pt-[35vh] pb-[55vh] md:pt-[35vh] md:pb-[55vh]">
      <p className={typography.eyebrow}>Field Office · Studio</p>
      <ScrollText
        as="p"
        split="char"
        fill="color"
        offset={[0.85, 0.45]}
        className={cn(typography.display, "mt-6 max-w-5xl")}
      >
        Four people making <ScrollTextHighlight>brand systems</ScrollTextHighlight>,{" "}
        <ScrollTextHighlight>product interfaces</ScrollTextHighlight> and the small tools that hold them together.
      </ScrollText>
    </Section>
  )
}
```

### Two-column about

An about page with a pinned portrait column beside paragraphs that each fill in as they pass through the middle of the screen. Scroll the preview.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Section } from "@/components/portfolio/section"
import { ScrollText } from "@/components/portfolio/scroll-text"
import { typography } from "@/lib/typography"

const paragraphs = [
  "I started as a print designer, setting timetables for a regional rail company. It taught me that most design is making dense information feel obvious.",
  "Since 2019 I’ve led design at Halcyon Labs, where a team of six ships the scheduling tools nurses use on every shift in forty hospitals.",
  "Outside work I run a small letterpress studio, teach an evening course on information design and walk the coast with a film camera.",
]

export default function ScrollTextAbout() {
  return (
    <Section>
      <div className="grid gap-10 md:grid-cols-[minmax(0,2fr)_minmax(0,3fr)] md:gap-16">
        <div className="flex flex-col gap-6 md:sticky md:top-12 md:self-start">
          <p className={typography.eyebrow}>About</p>
          <GenerativeArt
            seed="mara-lind-portrait"
            variant="portrait"
            label="Portrait of Mara Lind"
            className="aspect-[4/5] max-w-72 overflow-hidden rounded-2xl border md:max-w-none"
          />
          <p className={typography.meta}>Mara Lind · Copenhagen</p>
        </div>
        <div className="flex flex-col gap-12 pb-[40vh] md:gap-16 md:pt-[20vh]">
          {paragraphs.map((text) => (
            <ScrollText key={text} offset={[0.8, 0.5]} className="font-heading text-2xl leading-snug text-pretty md:text-3xl">
              {text}
            </ScrollText>
          ))}
        </div>
      </div>
    </Section>
  )
}
```

## API Reference

### ScrollText

A paragraph or heading that fills in, unit by unit, while it scrolls from `offset[0]` to
`offset[1]` of the viewport. Scrolling back dims it again. Screen readers get the text once, as
written; reduced motion, print and pages without JavaScript show it fully lit.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `React.ReactNode` | — | The text. Plain text and `ScrollTextHighlight` words; any other element is flattened to its text, so keep links and buttons outside. |
| `as` | `"p" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "div"` | `"p"` | Element to render. Pick the right heading level for the page outline. |
| `split` | `"word" \| "char"` | `"word"` | Light up word by word, or character by character (long texts fall back to words). |
| `fill` | `"opacity" \| "color"` | `"opacity"` | How unread text is dimmed. `opacity` fades it to `from`; `color` tints it with `muted-foreground` (override with a `--scroll-text-dim` colour). Both keep unread display-size text at 3:1 contrast or more; for body-size text use `color`, which keeps 4.5:1. |
| `from` | `number` | `0.5` | Opacity of unread text with `fill="opacity"`, `0`–`1`. The default keeps unread large text (24 px and up) at 3:1 or more against the page background; lower values fail WCAG contrast. Accent words (`ScrollTextHighlight`) never dim below `0.8`, for the same reason. |
| `offset` | `[start: number, end: number]` | `[0.9, 0.4]` | Where the fill starts and ends, as fractions of the viewport height from the top: it starts when the text's top reaches `offset[0]` and is complete when its bottom reaches `offset[1]`. Text near the end of the page that can't scroll that far completes when the page is scrolled to the bottom. |
| `disabled` | `boolean` | `false` | Show the text fully lit and stop tracking scroll (it's already off with reduced motion). |

Also accepts every `p` prop.

### ScrollTextHighlight

Words inside `ScrollText` that light up in the accent ink (`text-highlight-ink`) instead of the
text colour. Style it further with `className` (an underline, a heavier weight).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `React.ReactNode` | — | The highlighted words, as plain text. |

Also accepts every `span` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)



---

# Scroll Zoom

> A cover image or video that starts as an inset card and grows to full-bleed while the reader scrolls past it, for case-study openers and showreels.

Category: Effects · Registry item: `@portfolio-kit/scroll-zoom` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/scroll-zoom) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/scroll-zoom.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/scroll-zoom
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/scroll-zoom.tsx` and the kit items it uses: `use-composed-refs`, `use-reduced-motion`, `use-scroll-progress`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  ScrollZoom,
  ScrollZoomCaption,
  ScrollZoomMedia,
} from "@/components/portfolio/scroll-zoom"

<ScrollZoom from={0.7} radius="lg">
  <ScrollZoomMedia>
    <img src="/work/cover.jpg" alt="The Tidewater app on a phone, held over a harbour map" />
  </ScrollZoomMedia>
  <ScrollZoomCaption>
    <h2 className="font-heading text-4xl">Tidewater</h2>
  </ScrollZoomCaption>
</ScrollZoom>
```

## Examples

### Demo

A case-study cover that opens from an inset card to the full screen as you scroll, then fades in the project title. Scroll the preview.

```tsx
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { ScrollZoom, ScrollZoomCaption, ScrollZoomMedia } from "@/components/portfolio/scroll-zoom"
import { Section } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

export default function ScrollZoomDemo() {
  return (
    <article>
      <Section className="pb-12 md:pb-16">
        <p className={typography.eyebrow}>Case study · Tidewater Energy · 2026</p>
        <h1 className={cn(typography.title, "mt-4 max-w-3xl")}>One control room for 140 offshore turbines</h1>
        <p className={cn(typography.lead, "mt-4 max-w-2xl")}>
          Operators watched the fleet across four tools. We gave them one screen, built around the alerts they act on.
        </p>
      </Section>
      <ScrollZoom from={0.7} radius="lg">
        <ScrollZoomMedia>
          {/* Your cover: <img src="/work/tidewater.jpg" alt="…" /> or <Media src="…" ratio="auto" radius="none" />. */}
          <GenerativeArt seed="tidewater-control-room" variant="interface" label="The Tidewater fleet dashboard" />
        </ScrollZoomMedia>
        <ScrollZoomCaption>
          <p className={cn(typography.eyebrow, "text-foreground/85")}>Product design · Field research</p>
          <p className={cn(typography.title, "mt-3 max-w-3xl")}>Calm screens for the night shift.</p>
        </ScrollZoomCaption>
      </ScrollZoom>
      <Section>
        <p className={cn(typography.lead, "max-w-2xl")}>
          We sat with three shifts in Esbjerg and mapped every alert they acted on, and the ninety they learned to ignore.
          The new dashboard shows the twelve that matter, in the order the crew handles them.
        </p>
      </Section>
    </article>
  )
}
```

### Showreel opener

A filmmaker’s reel opens from a small window to the whole screen behind a title that stays readable throughout. Uses the kit’s `Media` for the looping clip.

```tsx
import { cn } from "@/lib/utils"
import { Media } from "@/components/portfolio/media"
import { ScrollZoom, ScrollZoomCaption, ScrollZoomMedia } from "@/components/portfolio/scroll-zoom"
import { Section } from "@/components/portfolio/section"
import { typography } from "@/lib/typography"

export default function ScrollZoomShowreel() {
  return (
    <div>
      <ScrollZoom from={0.55} radius="default" distance={1.25}>
        <ScrollZoomMedia zoom={1.2}>
          {/* Your clip: a file in public/ ("/reel.mp4") or a CDN URL. The demo clip sits next to the docs preview. */}
          <Media video="media/showreel.mp4" ratio="auto" radius="none" />
        </ScrollZoomMedia>
        <ScrollZoomCaption align="center" reveal={false}>
          <p className={cn(typography.eyebrow, "text-balance text-foreground")}>Showreel 2026 · 2:14</p>
          <h1 className={cn(typography.display, "mt-4 max-w-4xl")}>Ines Morrow</h1>
          <p className={cn(typography.lead, "mt-4 max-w-md text-balance text-foreground")}>
            Documentary and brand films from the edge of the Atlantic.
          </p>
        </ScrollZoomCaption>
      </ScrollZoom>
      <Section>
        <p className={typography.eyebrow}>Selected films</p>
        <p className={cn(typography.lead, "mt-4 max-w-2xl")}>
          Twelve years on location, from the Azores to the Faroe Islands, for clients including Atlantic Trust, Nordvind and
          the Faroese Tourist Board.
        </p>
      </Section>
    </div>
  )
}
```

## API Reference

### ScrollZoom

The scroll track and its sticky, clipped frame. Place it full width, outside a `Container`, and
not inside an `overflow: hidden/auto` ancestor (that stops `position: sticky`). Reduced motion,
print and pages without JavaScript show the media full-size with no scroll effect.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `React.ReactNode` | — | `ScrollZoomMedia` and, optionally, a `ScrollZoomCaption`. |
| `from` | `number` | `0.7` | Size of the frame before it grows, as a fraction of the full-bleed frame's width and height (`0.4`–`1`). `0.7` starts as a card 70% of the viewport wide and high. |
| `radius` | `"none" \| "default" \| "lg"` | `"lg"` | Corner radius of the inset frame; it stays until the frame is nearly full-bleed, then shrinks to square. |
| `distance` | `number` | `1` | How far the reader scrolls while the frame grows, in viewport heights. The frame stays pinned for this distance, then scrolls away at full-bleed. |
| `grow` | `number` | `0.8` | Fraction of the scroll distance spent growing; the rest holds the full-bleed frame so the caption can be read. |
| `frameClassName` | `string` | — | Classes for the sticky frame, e.g. a shorter frame than the viewport: `h-[80dvh]`. |
| `disabled` | `boolean` | `false` | Show the frame full-bleed and still (it's already still with reduced motion and in print). |

Also accepts every `div` prop.

### ScrollZoomMedia

The picture: an `<img>`, `<video>`, `<GenerativeArt />` or a kit `Media`, cropped to fill the frame.
Give images a real `alt` when they carry meaning.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `zoom` | `number` | `1.1` | Extra scale while the frame is inset, settling to `1` at full-bleed, so the picture seems to pull back as it opens up. `1` turns it off. |

Also accepts every `div` prop.

### ScrollZoomCaption

Copy over the media, on a black scrim (light text in both modes). Put your own heading, text and
links in it. It's always visible with reduced motion, in print and without JavaScript.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"bottom" \| "center" \| null` | `"bottom"` | `bottom`: copy in the lower corner over a gradient. `center`: a centred title over an even scrim. |
| `reveal` | `boolean \| null` | `true` | Fade the caption in over the last stretch of growth, once the frame is nearly full-bleed (earlier, the inset would clip its edges). Turn it off only with `align="center"`, for a title that should read from the start: a centred caption is padded to stay inside the inset card. |

Also accepts every `div` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)



---

# Section

> Page section with container widths, vertical spacing and a composable header: eyebrow, title, description and actions.

Category: Layout · Registry item: `@portfolio-kit/section` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/section) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/section.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/section
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/section.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  Section,
  SectionContent,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

<Section id="work">
  <SectionHeader>
    <SectionEyebrow index={1}>Selected work</SectionEyebrow>
    <SectionTitle>Interfaces for teams who sweat the details</SectionTitle>
    <SectionDescription>A handful of recent projects, each shipped end to end.</SectionDescription>
  </SectionHeader>
  <SectionContent>
    <p>Your content</p>
  </SectionContent>
</Section>
```

## Examples

### Demo

A section with an indexed eyebrow, title and lead above a grid of projects.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import {
  Section,
  SectionContent,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const projects = [
  { slug: "lumen", title: "Lumen", year: 2025, role: "Design system", art: "interface" },
  { slug: "tidewater", title: "Tidewater", year: 2025, role: "Product design", art: "interface" },
  { slug: "fieldnote", title: "Fieldnote", year: 2024, role: "Brand & web", art: "bauhaus" },
] as const

export default function SectionDemo() {
  return (
    <Section id="work">
      <SectionHeader>
        <SectionEyebrow index={1}>Selected work</SectionEyebrow>
        <SectionTitle>Interfaces for teams who sweat the details</SectionTitle>
        <SectionDescription>
          A handful of recent projects across product, brand and open source — each shipped end to end.
        </SectionDescription>
      </SectionHeader>
      <SectionContent className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
        {projects.map((project) => (
          <ProjectCard key={project.slug} variant="minimal" href={`#${project.slug}`}>
            <ProjectCardMedia>
              <GenerativeArt seed={project.slug} variant={project.art} />
            </ProjectCardMedia>
            <ProjectCardContent>
              <ProjectCardMeta>
                <span>{project.year}</span>
                <span>{project.role}</span>
              </ProjectCardMeta>
              <ProjectCardTitle>{project.title}</ProjectCardTitle>
            </ProjectCardContent>
          </ProjectCard>
        ))}
      </SectionContent>
    </Section>
  )
}
```

### Centered

A centered header with actions, for call-to-action bands, service intros and page endings.

```tsx
import { buttonVariants } from "@/components/ui/button"
import {
  Section,
  SectionActions,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

export default function SectionCentered() {
  return (
    <Section tone="muted">
      <SectionHeader align="center">
        <SectionEyebrow>Services</SectionEyebrow>
        <SectionTitle>How I can help</SectionTitle>
        <SectionDescription>
          From a two-week sprint to a year-long partnership — fixed scopes, clear prices, no surprises.
        </SectionDescription>
        <SectionActions className="mt-2">
          <a href="#contact" className={buttonVariants({ size: "lg" })}>
            Start a project
          </a>
          <a href="#work" className={buttonVariants({ variant: "outline", size: "lg" })}>
            See work
          </a>
        </SectionActions>
      </SectionHeader>
    </Section>
  )
}
```

### Split Header

Title on the left and a “view all” link on the right, for lists of writing, work or talks.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { PostList, PostListItem } from "@/components/portfolio/post-list"
import {
  Section,
  SectionContent,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"

const posts = [
  { slug: "motion", title: "Designing motion that respects attention", date: "2025-09-02", readingTime: "7 min" },
  { slug: "tokens", title: "Tokens are an API: versioning a design system", date: "2025-06-18", readingTime: "11 min" },
  { slug: "navigation", title: "The case for boring navigation", date: "2025-03-04", readingTime: "5 min" },
]

export default function SectionSplit() {
  return (
    <Section>
      <SectionHeader align="split">
        <div className="flex flex-col gap-4">
          <SectionEyebrow index="02">Writing</SectionEyebrow>
          <SectionTitle>Notes from the studio</SectionTitle>
        </div>
        <ArrowLink href="#writing" className="shrink-0">
          All articles
        </ArrowLink>
      </SectionHeader>
      <SectionContent>
        <PostList>
          {posts.map((post) => (
            <PostListItem
              key={post.slug}
              href={`#${post.slug}`}
              heading={post.title}
              date={post.date}
              readingTime={post.readingTime}
            />
          ))}
        </PostList>
      </SectionContent>
    </Section>
  )
}
```

## API Reference

### Container

Centered, padded page column. Use it on its own to align headers, footers and heroes with your sections.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg" \| "full" \| null` | `"default"` | Max width: `sm` (48rem, reading width), `default` (72rem), `lg` (80rem) or `full` (edge to edge, padding only). |

Also accepts every `div` prop.

### Section

A `<section>` with the kit's vertical rhythm and a centered container. When it contains a
`SectionTitle`, the section is automatically labelled by it (`aria-labelledby`), so it shows
up as a named region (landmark) for assistive tech: right for page-level parts like Work,
About or Contact. Without a title it stays an unnamed, plain section. Your own `aria-label` or
`aria-labelledby` wins. For repeated groups inside a page (one block per skill or category)
use a plain element or a component's own grouping instead, so the landmark list stays short.
Sections leave room for a sticky header when scrolled to via `#id`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `spacing` | `"none" \| "sm" \| "default" \| "lg" \| null` | `"default"` | Vertical padding (smaller in print). `none` when you manage spacing yourself. |
| `tone` | `"default" \| "muted" \| "card" \| null` | `"default"` | Background: transparent, a muted band, or the card surface. Alternate tones to separate sections. |
| `divider` | `boolean \| null` | `false` | Draw a top border between this section and the previous one. |
| `size` | `"sm" \| "default" \| "lg" \| "full" \| false` | `"default"` | Container width. Pass `false` to render children without a container (full-bleed content). |

Also accepts every `section` prop.

### SectionHeader

Groups the eyebrow, title, description and actions of a section.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "split" \| null` | `"start"` | `start` stacks everything on the left. `center` centers the text and actions, for CTA bands and page closers. `split` puts the first child (usually eyebrow + title) on the left and the last (a "view all" link, actions) bottom-aligned on the right from `md` up. |

Also accepts every `div` prop.

### SectionEyebrow

Small mono label above the title.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number \| string` | — | Optional index rendered before the label in the accent color, e.g. `1` → "01". Strings are shown as-is. |

Also accepts every `p` prop.

### SectionTitle

The section heading. Also names the surrounding `Section` for screen readers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h1" \| "h2" \| "h3"` | `"h2"` | Heading level. Use `h1` for the first section of a page without a hero. |

Also accepts every `h2` prop.

### SectionDescription

Lead paragraph under the title.

Also accepts every `p` prop.

### SectionActions

A row of buttons or links in the header. Centered automatically in a `center` header.

Also accepts every `div` prop.

### SectionContent

The body of the section, spaced consistently below the header.

Also accepts every `div` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)
- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md)
- [Not Found](https://www.parthjadhav.com/products/portfolio-kit/templates/not-found.md)
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)
- [Résumé](https://www.parthjadhav.com/products/portfolio-kit/templates/resume.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)
- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Service Card

> Offer or pricing card with name, description, price, a checklist of what's included and a call to action. A featured variant highlights the offer you recommend.

Category: Services · Registry item: `@portfolio-kit/service-card` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/service-card) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/service-card.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/service-card
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/service-card.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`, `radix-ui`.

shadcn/ui primitives: `button`.

## Usage

```tsx
import {
  ServiceCard,
  ServiceCardAction,
  ServiceCardDescription,
  ServiceCardFeatures,
  ServiceCardHeader,
  ServiceCardPrice,
  ServiceCardTitle,
} from "@/components/portfolio/service-card"

<ServiceCard>
  <ServiceCardHeader>
    <ServiceCardTitle>Sprint</ServiceCardTitle>
    <ServiceCardDescription>A focused two-week engagement.</ServiceCardDescription>
  </ServiceCardHeader>
  <ServiceCardPrice prefix="from" currency="€" amount={8000} cadence="/project" />
  <ServiceCardFeatures features={["Kickoff workshop", "Clickable prototype"]} />
  <ServiceCardAction href="#contact">Book a sprint</ServiceCardAction>
</ServiceCard>
```

## Examples

### Demo

Package an offer: what it is, what it costs, what's included and one clear next step.

```tsx
import {
  ServiceCard,
  ServiceCardAction,
  ServiceCardDescription,
  ServiceCardFeatures,
  ServiceCardHeader,
  ServiceCardPrice,
  ServiceCardTitle,
} from "@/components/portfolio/service-card"

export default function ServiceCardDemo() {
  return (
    <ServiceCard className="w-full max-w-sm">
      <ServiceCardHeader>
        <ServiceCardTitle>Sprint</ServiceCardTitle>
        <ServiceCardDescription>A focused two-week engagement to unblock one hard problem.</ServiceCardDescription>
      </ServiceCardHeader>
      <ServiceCardPrice prefix="from" currency="€" amount={8000} cadence="/project" />
      <ServiceCardFeatures
        features={[
          "Kickoff workshop",
          "Two weeks of design & build",
          "Clickable prototype or shipped feature",
          "Handover call & walkthrough",
        ]}
      />
      <ServiceCardAction href="#contact">Book a sprint</ServiceCardAction>
    </ServiceCard>
  )
}
```

### Featured

Highlight the offer you recommend with an accent border, a badge on the top edge and a solid button.

```tsx
import {
  ServiceCard,
  ServiceCardAction,
  ServiceCardDescription,
  ServiceCardFeatures,
  ServiceCardHeader,
  ServiceCardPrice,
  ServiceCardTitle,
} from "@/components/portfolio/service-card"

export default function ServiceCardFeatured() {
  return (
    <ServiceCard featured className="mt-3 w-full max-w-sm">
      <ServiceCardHeader>
        <ServiceCardTitle>Partnership</ServiceCardTitle>
        <ServiceCardDescription>Embedded with your team as a design engineer, month to month.</ServiceCardDescription>
      </ServiceCardHeader>
      <ServiceCardPrice currency="€" amount={12000} cadence="/month" note="Minimum 3 months" />
      <ServiceCardFeatures
        features={[
          "3 days a week, fully embedded",
          "Design system ownership",
          "Weekly demos & async updates",
          "Pause or cancel anytime",
        ]}
      />
      <ServiceCardAction href="#contact">Start a partnership</ServiceCardAction>
    </ServiceCard>
  )
}
```

### Pricing Tiers

Three offers side by side; CSS subgrid keeps titles, prices, features and buttons aligned across cards.

```tsx
import {
  Section,
  SectionContent,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import {
  ServiceCard,
  ServiceCardAction,
  ServiceCardDescription,
  ServiceCardFeatures,
  ServiceCardHeader,
  ServiceCardPrice,
  ServiceCardTitle,
} from "@/components/portfolio/service-card"

const tiers = [
  {
    name: "Sprint",
    description: "A focused two-week engagement to unblock one hard problem.",
    prefix: "from",
    amount: 8000,
    cadence: "/project",
    features: ["Kickoff workshop", "Two weeks of design & build", "Handover call & walkthrough"],
    cta: "Book a sprint",
  },
  {
    name: "Partnership",
    description: "Embedded with your team as a design engineer, month to month.",
    amount: 12000,
    cadence: "/month",
    note: "Minimum 3 months",
    features: ["3 days a week, fully embedded", "Design system ownership", "Weekly demos & async updates", "Pause or cancel anytime"],
    cta: "Start a partnership",
    featured: true,
  },
  {
    name: "Advisory",
    description: "Senior eyes on your product without the full-time cost.",
    amount: 1500,
    cadence: "/month",
    features: ["Monthly strategy call", "Async design & code reviews", "Hiring support"],
    cta: "Get in touch",
  },
]

export default function ServiceCardTiers() {
  return (
    <Section>
      <SectionHeader align="center">
        <SectionEyebrow>Ways to work together</SectionEyebrow>
        <SectionTitle>Simple, transparent engagements</SectionTitle>
        <SectionDescription>Fixed scopes, clear prices. Every engagement starts with a free 30-minute call.</SectionDescription>
      </SectionHeader>
      <SectionContent>
        {/* A list, so screen readers hear "3 items"; the item and the card both follow the shared rows. */}
        <ul role="list" className="grid gap-6 lg:grid-cols-3">
          {tiers.map((tier) => (
            <li key={tier.name} className="lg:row-span-4 lg:grid lg:grid-rows-subgrid lg:gap-8">
              <ServiceCard featured={tier.featured} className="lg:row-span-4 lg:grid lg:grid-rows-subgrid">
                <ServiceCardHeader>
                  <ServiceCardTitle>{tier.name}</ServiceCardTitle>
                  <ServiceCardDescription>{tier.description}</ServiceCardDescription>
                </ServiceCardHeader>
                <ServiceCardPrice
                  prefix={tier.prefix}
                  currency="€"
                  amount={tier.amount}
                  cadence={tier.cadence}
                  note={tier.note}
                />
                <ServiceCardFeatures features={tier.features} />
                <ServiceCardAction href="#contact">{tier.cta}</ServiceCardAction>
              </ServiceCard>
            </li>
          ))}
        </ul>
      </SectionContent>
    </Section>
  )
}
```

### Custom Price

Any string works as the amount (“Let's talk” for scoped work), and the badge text is yours to change.

```tsx
import {
  ServiceCard,
  ServiceCardAction,
  ServiceCardDescription,
  ServiceCardFeatures,
  ServiceCardHeader,
  ServiceCardPrice,
  ServiceCardTitle,
} from "@/components/portfolio/service-card"

export default function ServiceCardCustomPrice() {
  return (
    <ServiceCard featured badge="2 spots left" className="mt-3 w-full max-w-sm">
      <ServiceCardHeader>
        <ServiceCardTitle>Retainer</ServiceCardTitle>
        <ServiceCardDescription>A standing slot on my calendar for teams with a steady roadmap.</ServiceCardDescription>
      </ServiceCardHeader>
      <ServiceCardPrice amount="Let's talk" note="Scoped to your roadmap" />
      <ServiceCardFeatures features={["Priority scheduling", "Quarterly planning session", "Same-day replies"]} />
      <ServiceCardAction href="#contact">Request a proposal</ServiceCardAction>
    </ServiceCard>
  )
}
```

## API Reference

### ServiceCard

The card (`<article>`). Compose a header, price, features and action inside; the action sits at the bottom, so cards in a row line up.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `featured` | `boolean` | `false` | Highlight this offer: accent border, tinted background, a badge on the top edge, filled checks and a solid button. |
| `badge` | `React.ReactNode \| false` | `"Most popular"` | Badge on the top edge when featured. It's the only part screen readers hear as "featured", so keep it (or say so in the title) when you can. Pass `false` to hide. |

Also accepts every `article` prop.

### ServiceCardHeader

Groups the title and description.

Also accepts every `header` prop.

### ServiceCardTitle

The offer's name.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level. |

Also accepts every `h3` prop.

### ServiceCardDescription

One or two sentences on who the offer is for.

Also accepts every `p` prop.

### ServiceCardPrice

Large price with optional currency, prefix, cadence and note, read as one line ("from €8,000
/project"). Numbers use tabular figures; write the cadence as you want it heard ("/month" or "per month").

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `amount` (required) | `number \| string` | — | The price. Numbers get thousands separators (`8000` → "8,000"); strings render as-is, e.g. "Let's talk". |
| `prefix` | `React.ReactNode` | — | Label before the amount, e.g. "from". |
| `currency` | `string` | — | Symbol placed before the amount, e.g. "€". |
| `cadence` | `React.ReactNode` | — | After the amount, e.g. "/project", "/month". |
| `note` | `React.ReactNode` | — | Small print under the price. |
| `locale` | `string` | `"en-US"` | Locale used to format numeric amounts, e.g. `"de-DE"` → "8.000". |

Also accepts every `div` prop.

### ServiceCardFeatures

Checklist of what's included. Grows to fill the card, so actions line up across a row of cards.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `features` | `React.ReactNode[]` | — | Convenience: plain strings rendered as `ServiceCardFeature`s. |

Also accepts every `ul` prop.

### ServiceCardFeature

One checklist item. Use it directly for rich content (links, emphasis).

Also accepts every `li` prop.

### ServiceCardAction

Full-width call to action, 44px tall: solid when the card is featured, outlined otherwise. An `<a>`
(give it an `href`), or your own element with `asChild`. `target="_blank"` shows ↗ and tells screen
readers it opens a new tab.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` | — | Render your own element instead of `<a>`: a router `<Link>` or a `<button>` that opens a booking dialog. Pass it as the only child; styles and the arrow are merged onto it. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added when the link opens in a new tab (`target="_blank"`). |

Also accepts every `a` prop.



---

# Service List

> Numbered list of services with big headings that expand to reveal details, deliverables, duration and price. Keyboard-accessible accordion.

Category: Services · Registry item: `@portfolio-kit/service-list` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/service-list) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/service-list.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/service-list
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/service-list.tsx` and the kit items it uses: `typography`.

npm dependencies: `lucide-react`, `radix-ui`.

## Usage

```tsx
import {
  ServiceItem,
  ServiceList,
} from "@/components/portfolio/service-list"

<ServiceList defaultValue="Design systems">
  <ServiceItem
    heading="Design systems"
    description="Tokens, components and docs your team will actually use."
    deliverables={["Token pipeline", "Component library"]}
    duration="6–10 weeks"
    price="from €24k"
  />
  <ServiceItem heading="Product sprints" description="Two weeks to unblock one hard problem." />
</ServiceList>
```

## Examples

### Demo

Big, numbered service titles that open to reveal the pitch, deliverables, timeline and price.

```tsx
import {
  Section,
  SectionContent,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import { ServiceItem, ServiceList } from "@/components/portfolio/service-list"

const services = [
  {
    title: "Design systems",
    description:
      "Tokens, components and documentation that let a product team ship consistent UI without waiting on design. Built in Figma and code, side by side.",
    deliverables: ["Token architecture", "React component library", "Storybook docs", "Contribution guide"],
    duration: "8–12 weeks",
    price: "from €24k",
  },
  {
    title: "Product design",
    description: "From a rough brief to a tested, high-fidelity prototype your engineers can build from with confidence.",
    deliverables: ["Discovery workshop", "Flows & wireframes", "Hi-fi prototype", "Usability testing"],
    duration: "4–8 weeks",
    price: "from €14k",
  },
  {
    title: "Marketing sites",
    description: "Fast, accessible, animated sites on a CMS your team can actually edit.",
    deliverables: ["Art direction", "Next.js build", "CMS setup", "Analytics"],
    duration: "3–6 weeks",
    price: "from €9k",
  },
  {
    title: "Front-end audits",
    description: "A focused review of performance, accessibility and UI architecture with a prioritized plan.",
    deliverables: ["Audit report", "Fix roadmap", "Team walkthrough"],
    duration: "1–2 weeks",
    price: "€3.5k fixed",
  },
]

export default function ServiceListDemo() {
  return (
    <Section>
      <SectionHeader>
        <SectionEyebrow index={3}>Services</SectionEyebrow>
        <SectionTitle>What I can help with</SectionTitle>
      </SectionHeader>
      <SectionContent>
        <ServiceList defaultValue={services[0].title}>
          {services.map(({ title, ...service }) => (
            <ServiceItem key={title} heading={title} {...service} />
          ))}
        </ServiceList>
      </SectionContent>
    </Section>
  )
}
```

### Custom Content

Skip the data props and put anything inside an item: a paragraph, a list of formats, a booking link.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { Section } from "@/components/portfolio/section"
import { ServiceItem, ServiceList } from "@/components/portfolio/service-list"
import { typography } from "@/lib/typography"

const formats = [
  { name: "Motion for product teams", length: "Half day" },
  { name: "Design tokens, end to end", length: "Full day" },
  { name: "Accessible components", length: "Half day" },
]

export default function ServiceListCustomContent() {
  return (
    <Section size="sm">
      <ServiceList defaultValue="Workshops">
        <ServiceItem heading="Workshops">
          <p className={typography.lead}>Hands-on sessions for teams of up to 12, remote or on site.</p>
          <ul role="list" className="flex flex-col border-t">
            {formats.map((format) => (
              <li key={format.name} className="flex items-baseline justify-between gap-4 border-b py-3">
                <span className="text-sm md:text-base">{format.name}</span>
                <span className={typography.meta}>{format.length}</span>
              </li>
            ))}
          </ul>
          <ArrowLink href="#contact" className="self-start text-sm">
            Book a workshop
          </ArrowLink>
        </ServiceItem>
        <ServiceItem heading="Advisory" description="A standing monthly call and async design and code reviews." price="€1.5k / month" />
        <ServiceItem heading="Speaking" description="Talks on motion, design systems and craft for conferences and meetups." />
      </ServiceList>
    </Section>
  )
}
```

### With Images

A photographer’s packages with sample frames inside each panel, and `type="multiple"` so visitors can open several to compare.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  Section,
  SectionContent,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import { ServiceItem, ServiceList } from "@/components/portfolio/service-list"

const packages = [
  {
    title: "Editorial portraits",
    description: "Half a day on location for magazines, book jackets and team pages. Natural light first, one strobe if the room asks for it.",
    deliverables: ["20 edited frames", "Print-ready files", "Online gallery"],
    duration: "Half day",
    price: "from €1.8k",
    frames: [
      { variant: "portrait", seed: "Editorial portraits-0" },
      { variant: "portrait", seed: "Editorial portraits-1" },
      { variant: "portrait", seed: "Editorial portraits-2" },
    ] as const,
  },
  {
    title: "Product & still life",
    description: "Studio sets for ceramics, objects and packaging, lit to match your brand across the whole range.",
    deliverables: ["Up to 30 products", "Cut-outs", "Two set styles"],
    duration: "1–2 days",
    price: "from €3.2k",
    frames: [
      { variant: "bauhaus", seed: "Product & still life-0" },
      { variant: "orb", seed: "Product & still life-1" },
      { variant: "rings", seed: "Product & still life-2" },
    ] as const,
  },
  {
    title: "Weddings",
    description: "Quiet, documentary coverage from the morning to the first dance, with a printed album six weeks later.",
    deliverables: ["Full-day coverage", "400+ frames", "Linen album"],
    duration: "10 hours",
    price: "from €4.5k",
    frames: [
      { variant: "landscape", seed: "Weddings-0" },
      { variant: "portrait", seed: "Weddings-1" },
      { variant: "landscape", seed: "Weddings-2" },
    ] as const,
  },
]

export default function ServiceListWithImages() {
  return (
    <Section>
      <SectionHeader>
        <SectionEyebrow>Commissions</SectionEyebrow>
        <SectionTitle>Ways to work together</SectionTitle>
      </SectionHeader>
      <SectionContent>
        <ServiceList type="multiple" defaultValue={[packages[0].title]}>
          {packages.map(({ title, frames, ...service }) => (
            <ServiceItem key={title} heading={title} {...service}>
              <div className="grid grid-cols-3 gap-2 md:gap-3">
                {frames.map(({ variant, seed }) => (
                  <div key={seed} className="aspect-[4/5] overflow-hidden rounded-lg border bg-muted">
                    <GenerativeArt seed={seed} variant={variant} />
                  </div>
                ))}
              </div>
            </ServiceItem>
          ))}
        </ServiceList>
      </SectionContent>
    </Section>
  )
}
```

## API Reference

### ServiceList

The accordion root. `ServiceItem`s are numbered automatically with a CSS counter (01, 02, …);
the numbers are decorative, so screen readers hear each heading once. Enter or Space toggles an
item; the arrow keys, Home and End move between headings. Closed panels are left out of the page
until opened, except when printing: then every service prints in full.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `labels` | `ServiceListLabels` | — | Translate the built-in labels: `deliverables` ("Deliverables"), `duration` ("Duration") and `price` ("Investment"), e.g. `{ deliverables: "Leistungen", duration: "Dauer", price: "Preis" }`. |
| `type` | `"single" \| "multiple"` | `"single"` | `single` keeps one service open at a time (click again to close); `multiple` lets any number stay open. |
| `value` | `string \| string[]` | — | Open item (controlled): the item's `value`, which defaults to its heading. |
| `defaultValue` | `string \| string[]` | — | Item open on first render (uncontrolled), e.g. your main service. |
| `onValueChange` | `((value: string) => void) \| ((value: string[]) => void)` | — | Called with the open item's value (`""` when all are closed). |

Also accepts every `Accordion.Root` prop.

### ServiceItem

One service: a heading that contains the toggle button, and a labelled panel. Extra `children`
render in the expanded panel, after the description.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `React.ReactNode` | — | Service name, shown large. Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `value` | `string` | — | Unique value used by `defaultValue`/`value`; defaults to the heading when it is a string. |
| `description` | `React.ReactNode` | — | Short pitch shown when expanded. |
| `deliverables` | `string[]` | — | Deliverables rendered as tags. |
| `duration` | `React.ReactNode` | — | Typical timeline, e.g. "4–6 weeks". Shown beside the heading from `lg` up (and read as the button's description); in the expanded panel below `lg`. |
| `price` | `React.ReactNode` | — | e.g. "from €12k". Shown like `duration`. |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level wrapping the toggle button. Use `h4` when the list sits under an `h3`. |

Also accepts every `Accordion.Item` prop.

### type ServiceListLabels

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `deliverables` | `string` | — | Eyebrow above the deliverables. Default "Deliverables". |
| `duration` | `string` | — | Label for `duration` in the expanded panel (below `lg`). Default "Duration". |
| `price` | `string` | — | Label for `price` in the expanded panel (below `lg`). Default "Investment". |

## Used in templates

- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Showreel

> A large poster with a play button that follows the cursor; it opens your reel in a full-screen player (or plays it in place), with a duration label and a quiet coming-soon state.

Category: Hero · Registry item: `@portfolio-kit/showreel` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/showreel) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/showreel.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/showreel
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/showreel.tsx` and the kit items it uses: `typography`, `use-composed-refs`, `use-fine-pointer`, `use-in-view`, `use-page-visible`, `use-reduced-motion`, `use-save-data`.

npm dependencies: `lucide-react`, `radix-ui`.

## Usage

```tsx
import {
  Showreel,
  ShowreelCaption,
  ShowreelPoster,
} from "@/components/portfolio/showreel"

<Showreel src="/reel.mp4" duration="1:24" heading="Showreel 2026">
  <ShowreelPoster>
    <img src="/reel-poster.jpg" alt="" />
  </ShowreelPoster>
  <ShowreelCaption>
    <span>Showreel 2026</span>
  </ShowreelCaption>
</Showreel>
```

## Examples

### Demo

A motion designer’s hero: statement on top, the reel underneath. The play button drifts after your cursor; click to open the reel full screen.

```tsx
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Container } from "@/components/portfolio/section"
import { Showreel, ShowreelCaption, ShowreelPoster } from "@/components/portfolio/showreel"
import { typography } from "@/lib/typography"

export default function ShowreelDemo() {
  return (
    <Container className="flex flex-col gap-10 py-16 md:gap-14 md:py-24">
      <div className="flex flex-col gap-6 md:flex-row md:items-end md:justify-between">
        <h1 className={typography.display}>
          Motion for brands
          <br />
          that move.
        </h1>
        <p className={cn(typography.lead, "max-w-xs")}>Title sequences, product films and identity motion since 2016.</p>
      </div>
      {/* Point `src` at your own reel: a file in public/ ("/reel.mp4") or a CDN URL. The demo clip sits next to the docs preview. */}
      <Showreel src="media/showreel.mp4" duration="0:08" heading="Showreel 2026">
        <ShowreelPoster>
          <GenerativeArt seed="showreel-2026" variant="landscape" />
        </ShowreelPoster>
        <ShowreelCaption>
          <span className="font-heading text-lg md:text-xl">Showreel 2026</span>
          <span className="font-mono text-xs text-white/70">Selected work, 2023–26</span>
        </ShowreelCaption>
      </Showreel>
    </Container>
  )
}
```

### Inline

`mode="inline"` plays the reel inside the frame instead of full screen. Here the frame is portrait on phones and widescreen from `md` up.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Showreel, ShowreelCaption, ShowreelPoster } from "@/components/portfolio/showreel"

export default function ShowreelInline() {
  return (
    <Showreel
      mode="inline"
      // Your own film: a file in public/ ("/film.mp4") or a CDN URL. The demo clip sits next to the docs preview.
      src="media/showreel.mp4"
      duration="0:08"
      label="Watch the film"
      className="mx-auto aspect-[4/5] max-w-sm md:aspect-video md:max-w-3xl"
    >
      <ShowreelPoster>
        <GenerativeArt seed="tidewater-film" variant="landscape" />
      </ShowreelPoster>
      <ShowreelCaption>
        <span className="text-sm font-medium">Tidewater — launch film</span>
        <span className="font-mono text-xs text-white/70">Direction &amp; motion</span>
      </ShowreelCaption>
    </Showreel>
  )
}
```

### Coming soon

Leave out `src` while the reel is still in the edit: the poster stays, and the play button becomes a quiet label.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Showreel, ShowreelPoster } from "@/components/portfolio/showreel"

export default function ShowreelComingSoon() {
  return (
    <Showreel pendingLabel="2026 reel — in the edit" className="mx-auto max-w-3xl">
      <ShowreelPoster>
        <GenerativeArt seed="reel-in-edit" variant="landscape" />
      </ShowreelPoster>
    </Showreel>
  )
}
```

### With a preview loop

Add `preview` for a short, muted loop behind the play button. It plays only while on screen and never loads under reduced motion or Save-Data, where the poster stays.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Showreel, ShowreelCaption, ShowreelPoster } from "@/components/portfolio/showreel"

export default function ShowreelWithPreview() {
  return (
    <Showreel
      // Your files: a few seconds cut from the reel for `preview`, the full reel for `src`. The demo uses one clip for both.
      src="media/showreel.mp4"
      preview="media/showreel.mp4"
      duration="0:08"
      heading="Studio reel"
      className="mx-auto max-w-3xl"
    >
      <ShowreelPoster>
        <GenerativeArt seed="studio-reel-loop" variant="landscape" />
      </ShowreelPoster>
      <ShowreelCaption>
        <span className="text-sm font-medium">Studio reel</span>
        <span className="font-mono text-xs text-white/70">2024–26</span>
      </ShowreelCaption>
    </Showreel>
  )
}
```

## API Reference

### Showreel

The poster frame (16:9 by default — change it with `className`, e.g. `aspect-[4/5] md:aspect-video`).
Put a `<ShowreelPoster>` inside, and optionally a `<ShowreelCaption>`. The whole frame is one button.

The play button follows a mouse; with touch, the keyboard or reduced motion it stays centred. The
full-screen player keeps focus inside, closes with Escape, the close button or a click outside the
video, locks page scroll, pauses the reel and hands focus back to the poster.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | — | Video file of the full reel (MP4/WebM). Plays with sound and native controls once opened. |
| `embed` | `string` | — | Or an embed URL (Vimeo, YouTube…) shown in an iframe. Add the host's autoplay parameter yourself. |
| `preview` | `string` | — | A short, muted clip that loops behind the play button, over the poster. It plays only while on screen and is never loaded under reduced motion, `prefers-reduced-data` or Save-Data (the poster stays). |
| `duration` | `string` | — | Running time shown next to the label, e.g. `"1:42"`. |
| `label` | `string` | `"Play reel"` | Play button text. |
| `pendingLabel` | `string` | `"Reel coming soon"` | Shown instead of the play button when there is no `src` or `embed` yet. |
| `heading` | `string` | — | Name of the player (its dialog title and iframe title). Defaults to `label`. |
| `mode` | `"dialog" \| "inline"` | `"dialog"` | `dialog` opens a full-screen player that grows out of the poster; `inline` plays inside the frame. |
| `ratio` | `number` | `16 / 9` | Width ÷ height of the reel in the full-screen player. |
| `captions` | `string` | — | WebVTT captions for `src`, shown by default (strongly recommended if the reel has speech). Serve the file from the page's origin, or with CORS headers. |
| `unavailableLabel` | `string` | `"This reel can't be played right now."` | Message shown in the player when the video fails to load. |
| `labels` | `Partial<ShowreelLabels>` | — | Other built-in text, for translations: `{ close, captions, openFile, newTab }`. |
| `onPlayingChange` | `(playing: boolean) => void` | — | Called when the reel starts (opens) or stops (closes). |

Also accepts every `div` prop.

### ShowreelPoster

The still behind the play button: an `<img>` (cropped to fill), `<GenerativeArt />` or any artwork.
Zooms gently on hover. Must be a **direct** child of `<Showreel>` — the player reuses it while the reel loads.

Also accepts every `div` prop.

### ShowreelCaption

Text over the bottom of the poster (title, year, client), on a soft dark scrim. Clicks pass through
to the play button.

Also accepts every `div` prop.

### type ShowreelLabels

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `close` (required) | `string` | — | Close button of the full-screen player. |
| `captions` (required) | `string` | — | Name of the captions track in the video's menu. |
| `openFile` (required) | `string` | — | Link to the video file, shown when the reel can't play. |
| `newTab` (required) | `string` | — | Screen-reader text after that link, which opens in a new tab. |



---

# Sidenote

> Tufte-style margin notes: numbered references in the text with the notes beside it on wide screens, and tap-to-expand inline notes on phones.

Category: Content · Registry item: `@portfolio-kit/sidenote` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/sidenote) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/sidenote.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/sidenote
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/sidenote.tsx` and the kit items it uses: `use-composed-refs`, `use-media-query`.

## Usage

```tsx
import { Prose } from "@/components/portfolio/prose"
import { Sidenote, Sidenotes } from "@/components/portfolio/sidenote"

<Sidenotes>
  <Prose>
    <p>
      The twelve-column grid
      <Sidenote note="Popularised by print designers in the 1950s." /> survived anyway.
    </p>
  </Prose>
</Sidenotes>
```

## Examples

### Demo

Numbered notes beside an essay: in the margin on wide screens, tap the number to expand them on phones.

```tsx
import { Prose } from "@/components/portfolio/prose"
import { Sidenote, Sidenotes } from "@/components/portfolio/sidenote"

export default function SidenoteDemo() {
  return (
    <Sidenotes className="mx-auto max-w-5xl">
      <Prose>
        <h2>Why the grid came back</h2>
        <p>
          For a decade, web layout meant floats and clearfixes. The twelve-column grid
          <Sidenote note="Popularised by print designers in the 1950s, then by CSS frameworks around 2008." /> survived
          anyway, mostly as a set of class names nobody could explain.
        </p>
        <p>
          Subgrid changed that. Nested cards can finally align their titles and footers to the page
          <Sidenote
            note={
              <>
                Supported in every evergreen browser since late 2023. See the <a href="#subgrid">subgrid notes</a>.
              </>
            }
          />{" "}
          instead of guessing with fixed heights, which means a pricing table no longer breaks the moment one tier gets a
          longer description.
        </p>
        <p>
          The result is quieter code and calmer pages. Layout goes back to being a decision you make once, at the top,
          rather than a negotiation every component has with its neighbours.
          <Sidenote note="The same argument applies to spacing tokens: decide the scale once, then stop arguing about 14px." />
        </p>
      </Prose>
    </Sidenotes>
  )
}
```

### Margin notes

`variant="margin"` for unnumbered asides such as a definition or a source, mixed with numbered notes in the same paragraph.

```tsx
import { Prose } from "@/components/portfolio/prose"
import { Sidenote, Sidenotes } from "@/components/portfolio/sidenote"

export default function SidenoteMarginNotes() {
  return (
    <Sidenotes className="mx-auto max-w-5xl">
      <Prose>
        <p>
          A good loading state is honest about time. Skeletons
          <Sidenote
            variant="margin"
            note={
              <>
                <em>Skeleton screen:</em> a grey outline of the layout shown while content loads.
              </>
            }
          />{" "}
          promise that content is seconds away; a spinner promises nothing at all, which is why people abandon them
          sooner.
          <Sidenote note="Measured across four checkout flows in 2025; the effect vanished above ten seconds." />
        </p>
        <p>
          The rule we settled on: show structure when you know the shape, and a progress count when you know the length.
          Everything else is a spinner, and a spinner should be rare.
        </p>
      </Prose>
    </Sidenotes>
  )
}
```

## API Reference

### Sidenotes

The article column. Numbers every `Sidenote` inside it (CSS counters, so the numbering always
matches the text order) and, from `lg` up, reserves a margin on the right for the notes. Tune the
margin with `--sidenote-width` and `--sidenote-gap`, e.g. `className="lg:[--sidenote-width:18rem]"`.

Also accepts every `div` prop.

### Sidenote

Place it inside a paragraph, right after the word it annotates. From `lg` up the note floats into
the margin reserved by `Sidenotes`, level with its reference; below `lg` the reference is a button
that expands the note in place. The note is always in the DOM right after its reference, so screen
readers read it in context: on wide screens it is announced as "Note 1: …", on small screens the
button ("Note 1") exposes `aria-expanded` and controls the note. Printing shows every note inline.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `note` (required) | `React.ReactNode` | — | The note itself. Inline content only (it renders inside your paragraph): text, links, `<em>`, `<code>`. |
| `variant` | `"numbered" \| "margin"` | `"numbered"` | `numbered` puts a superscript number in the text and before the note. `margin` is an unnumbered aside (a Tufte "margin note"); on phones it's revealed by a small ⊕ button. |
| `defaultOpen` | `boolean` | `false` | Start expanded on small screens. On wide screens notes are always visible. |

Also accepts every `span` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)



---

# Signature

> A handwritten SVG signature that writes itself, stroke by stroke, when it scrolls into view — the sign-off at the end of a bio or letter.

Category: About · Registry item: `@portfolio-kit/signature` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/signature) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/signature.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/signature
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/signature.tsx` and the kit items it uses: `use-composed-refs`, `use-in-view`, `use-isomorphic-layout-effect`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { Signature, signatureVariants, signatureSample } from "@/components/portfolio/signature"
```

## Examples

### Demo

The close of a short letter on an about page: the signature writes itself, stroke by stroke, as the note scrolls into view.

```tsx
import { Signature } from "@/components/portfolio/signature"
import { typography } from "@/lib/typography"

export default function SignatureDemo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <p className={typography.body}>
        Thanks for reading this far. If something here sounds like your next project, write to me. I answer every
        email myself, usually within two days.
      </p>
      <p className={typography.body}>Warmly,</p>
      <div className="flex flex-col gap-1">
        <Signature name="Noa Vale" className="-ml-1" />
        <p className={typography.meta}>Noa Vale · Design engineer, Lisbon</p>
      </div>
    </div>
  )
}
```

### Your own signature

Pass the strokes of your own signature, exported from a design tool as centre-line paths, with their viewBox. Here in the accent ink.

```tsx
import { Signature } from "@/components/portfolio/signature"
import { typography } from "@/lib/typography"

// A fictional signature drawn by hand for this example (not traced from a font).
// One path per pen stroke, in writing order: the J's bar, its stem and loop, "un", the underline.
const jun = {
  viewBox: "24 10 192 104",
  paths: [
    "M49.2 24C62 20 80.4 18 96 20",
    "M78 20C71.2 44 64 70 55.6 92C49.8 106 36.4 108 34.4 98C33 90 45.2 84 57.6 82C70 80 80.8 76 90.4 68",
    "M90.4 68C96.4 58 102 50 104.8 46C100.8 56 96.8 66 99.6 72C102.8 76 109.6 72 115.2 64C118.4 58 121.6 52 124.8 46C120.8 56 116.8 66 119.6 72C121.2 74 125.6 72 130.8 66C136.4 58 142 50 146.8 46C145.2 54 141.2 64 137.6 72C144 60 152.4 48 160.8 46C166.8 46 162.4 58 160.8 66C159.6 72 163.2 74 170 70",
    "M101.6 92C136.8 86 177.2 84 206.4 88",
  ],
}

export default function SignatureCustom() {
  return (
    <figure className="flex w-full max-w-xs flex-col items-start gap-3">
      <Signature name="Jun" tone="highlight" paths={jun.paths} viewBox={jun.viewBox} strokeWidth={3} duration={1800} />
      <figcaption className={typography.meta}>Jun Park · Illustrator</figcaption>
    </figure>
  )
}
```

### In a bio

Signing off an about section in place of a typed closing line, beside a portrait.

```tsx
import { Bio, BioContent, BioFact, BioFacts, BioPortrait } from "@/components/portfolio/bio"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Signature } from "@/components/portfolio/signature"

export default function SignatureInBio() {
  return (
    <Bio className="mx-auto w-full max-w-5xl py-8 md:py-12">
      <BioPortrait caption="At the studio, Lisbon">
        <GenerativeArt seed="signature-noa" variant="portrait" />
      </BioPortrait>
      <BioContent>
        <p>I&rsquo;m Noa, a design engineer working between product design and front-end code.</p>
        <p>
          For eight years I&rsquo;ve helped small teams turn complicated tools into calm ones. These days I lead the
          design system at Halcyon Labs and take on one or two projects of my own each year.
        </p>
        <BioFacts>
          <BioFact label="Based in">Lisbon, PT</BioFact>
          <BioFact label="Focus">Design systems</BioFact>
        </BioFacts>
        <Signature name="Noa Vale" duration={2000} className="mt-2 -ml-1 h-14 md:h-16" />
      </BioContent>
    </Bio>
  )
}
```

## API Reference

### Signature

The signature, as an `<svg role="img">` named by `name`, coloured with `currentColor` (set by
`tone`). Size it with a height class (`h-16 md:h-20` by default); the width follows and the drawing
stays start-aligned if the box is stretched. With reduced
motion, without JavaScript and in print it's shown fully written.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | The name the signature spells. It's the image's accessible name, so screen readers hear it. |
| `strokeWidth` | `number` | `2.8` | Line weight in `viewBox` units, so it scales with the signature. |
| `viewBox` | `string` | `signatureSample.viewBox` | The `viewBox` your paths were drawn in. Required with your own `paths`. |
| `tone` | `"foreground" \| "highlight" \| "muted"` | `"foreground"` | `foreground` (ink), `highlight` (the theme accent as ink) or `muted`. |
| `paths` | `readonly string[]` | `signatureSample.paths` | Your signature as SVG path data (`d` attributes), one pen stroke per path, in the order you'd write them. Use centre-line strokes, not outlined shapes: export a stroked path from Figma or Illustrator (or draw one with the pen tool), copy each `d`, and the `viewBox` with it. Outlined (filled) shapes, as exported from a font or a scan, have no single line to draw and won't work. Defaults to a sample signature. |
| `animate` | `boolean` | `true` | Write it on when it scrolls into view. `false` shows it at once (as reduced motion, print and no-JS do). |
| `duration` | `number` | `2400` | Total writing time in ms, shared between the strokes by their length. |
| `delay` | `number` | `0` | Delay before writing starts, in ms. |

Also accepts every `svg` prop.



---

# Site Footer

> Site footer with link columns, a small-print row and an optional giant wordmark that fills the full width.

Category: Layout · Registry item: `@portfolio-kit/site-footer` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/site-footer) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/site-footer.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/site-footer
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/site-footer.tsx` and the kit items it uses: `section`, `typography`, `use-composed-refs`, `use-isomorphic-layout-effect`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  SiteFooter,
  SiteFooterBottom,
  SiteFooterBrand,
  SiteFooterColumn,
  SiteFooterGrid,
  SiteFooterLink,
} from "@/components/portfolio/site-footer"

<SiteFooter>
  <SiteFooterGrid>
    <SiteFooterBrand>
      <p>Noa Vale</p>
    </SiteFooterBrand>
    <SiteFooterColumn heading="Elsewhere">
      <SiteFooterLink href="https://example.com" external>Newsletter</SiteFooterLink>
      <SiteFooterLink href="mailto:hello@example.com">Email</SiteFooterLink>
    </SiteFooterColumn>
  </SiteFooterGrid>
  <SiteFooterBottom>
    <p>© 2026 Noa Vale</p>
  </SiteFooterBottom>
</SiteFooter>
```

## Examples

### Demo

Brand block, link columns and a small-print row. External links get an ↗ and open in a new tab.

```tsx
import { ArrowUp } from "lucide-react"

import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import {
  SiteFooter,
  SiteFooterBottom,
  SiteFooterBrand,
  SiteFooterColumn,
  SiteFooterGrid,
  SiteFooterLink,
} from "@/components/portfolio/site-footer"
import { typography } from "@/lib/typography"

const columns = [
  {
    heading: "Sitemap",
    links: [
      { label: "Work", href: "#work" },
      { label: "About", href: "#about" },
      { label: "Writing", href: "#writing" },
      { label: "Contact", href: "#contact" },
    ],
  },
  {
    heading: "Selected work",
    links: [
      { label: "Lumen", href: "#lumen" },
      { label: "Tidewater", href: "#tidewater" },
      { label: "Fieldnote", href: "#fieldnote" },
      { label: "Orbit Analytics", href: "#orbit" },
    ],
  },
  {
    heading: "Elsewhere",
    links: [
      { label: "GitHub", href: "https://github.com/example" },
      { label: "LinkedIn", href: "https://www.linkedin.com/in/example" },
      { label: "Read.cv", href: "https://read.cv/example" },
      { label: "RSS", href: "https://example.com/rss.xml" },
    ],
  },
]

export default function SiteFooterDemo() {
  return (
    <SiteFooter>
      <SiteFooterGrid>
        <SiteFooterBrand>
          <p className="font-heading text-2xl">Noa Vale</p>
          <p className={typography.body}>I design and build calm, fast interfaces for ambitious product teams.</p>
          <AvailabilityBadge variant="soft" className="mt-2" />
        </SiteFooterBrand>
        {columns.map((column) => (
          <SiteFooterColumn key={column.heading} heading={column.heading}>
            {column.links.map((link) => (
              <SiteFooterLink key={link.href} href={link.href}>
                {link.label}
              </SiteFooterLink>
            ))}
          </SiteFooterColumn>
        ))}
      </SiteFooterGrid>
      <SiteFooterBottom>
        <p>© 2025 Noa Vale · Lisbon, Portugal</p>
        <div className="flex items-center gap-5">
          <a href="#colophon">Colophon</a>
          <a href="#top" className="inline-flex items-center gap-1.5">
            Back to top <ArrowUp aria-hidden className="size-3" />
          </a>
        </div>
      </SiteFooterBottom>
    </SiteFooter>
  )
}
```

### Big Wordmark

A closing call to action and a large name sized to span the container exactly.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import {
  SiteFooter,
  SiteFooterBottom,
  SiteFooterColumn,
  SiteFooterGrid,
  SiteFooterLink,
  SiteFooterWordmark,
} from "@/components/portfolio/site-footer"
import { typography } from "@/lib/typography"

export default function SiteFooterWordmarkExample() {
  return (
    <SiteFooter>
      <div className="flex flex-col gap-10 md:flex-row md:items-end md:justify-between">
        <div className="flex max-w-md flex-col gap-4">
          <p className={typography.eyebrow}>Have a project in mind?</p>
          <p className="font-heading text-3xl leading-[1.05] text-balance md:text-4xl">
            Let&apos;s build something calm and fast together.
          </p>
          <ArrowLink href="mailto:hello@example.com" underline="always" className="self-start">
            hello@example.com
          </ArrowLink>
        </div>
        <SiteFooterGrid className="md:gap-x-16">
          <SiteFooterColumn heading="Sitemap">
            <SiteFooterLink href="#work">Work</SiteFooterLink>
            <SiteFooterLink href="#about">About</SiteFooterLink>
            <SiteFooterLink href="#writing">Writing</SiteFooterLink>
          </SiteFooterColumn>
          <SiteFooterColumn heading="Elsewhere">
            <SiteFooterLink href="https://github.com/example">GitHub</SiteFooterLink>
            <SiteFooterLink href="https://www.linkedin.com/in/example">LinkedIn</SiteFooterLink>
            <SiteFooterLink href="https://dribbble.com/example">Dribbble</SiteFooterLink>
          </SiteFooterColumn>
        </SiteFooterGrid>
      </div>
      <SiteFooterWordmark>Noa Vale</SiteFooterWordmark>
      <SiteFooterBottom>
        <p>© 2025 Noa Vale. All rights reserved.</p>
        <a href="#top">Back to top</a>
      </SiteFooterBottom>
    </SiteFooter>
  )
}
```

### Cut Wordmark

A fading wordmark cut off at the bottom edge, below the small print.

```tsx
import { SiteFooter, SiteFooterBottom, SiteFooterWordmark } from "@/components/portfolio/site-footer"
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"

const socials = ["https://github.com/example", "https://x.com/example", "https://www.linkedin.com/in/example", "mailto:hello@example.com"]

export default function SiteFooterCutWordmark() {
  return (
    <SiteFooter>
      <SiteFooterBottom>
        <p>© 2025 Noa Vale · Design engineer</p>
        <SocialLinks className="-my-2 -ml-2 sm:ml-0">
          {socials.map((href) => (
            <SocialLink key={href} href={href} />
          ))}
        </SocialLinks>
      </SiteFooterBottom>
      <SiteFooterWordmark tone="fade" cut>
        noa vale
      </SiteFooterWordmark>
    </SiteFooter>
  )
}
```

## API Reference

### SiteFooter

The page footer. Stack a `SiteFooterGrid`, a `SiteFooterBottom` and optionally a `SiteFooterWordmark` inside, in any order.
Renders `<footer>`: as a direct child of `<body>` (or your page wrapper, not inside `<main>`, `<article>` or
`<section>`) it is the page's single `contentinfo` landmark, so use one per page.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg" \| "full"` | `"default"` | Container width. Match it to your sections and header. |

Also accepts every `footer` prop.

### SiteFooterGrid

Brand block + link columns. Two columns on mobile; from `md` up, columns share the remaining width equally.

Also accepts every `div` prop.

### SiteFooterBrand

Name, tagline, CTA… Spans two grid tracks.

Also accepts every `div` prop.

### SiteFooterColumn

A headed list of `SiteFooterLink`s. The heading names the list; columns are not landmarks.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` (required) | `React.ReactNode` | — | Column heading, e.g. "Sitemap" or "Elsewhere". It also labels the list of links. |
| `as` | `"h2" \| "h3" \| "h4"` | `"h2"` | Heading level for the column heading. Use `h3` when your footer sits under its own `h2`. |

Also accepts every `div` prop.

### SiteFooterLink

A link inside `SiteFooterColumn` (renders its own `<li>`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `external` | `boolean` | — | Open in a new tab, show an ↗ glyph and tell screen readers `newTabLabel`. Auto-detected from `href` (absolute `http(s)` URLs); pass `external={false}` to keep an absolute link in the same tab. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added when the link opens in a new tab. Translate it here. |

Also accepts every `a` prop.

### SiteFooterBottom

Small-print row: ©, legal links, credits, back-to-top. Plain `<a>`s inside get hover and focus styles and
a 24px tall hit area (vertical padding that doesn't change the layout).

Also accepts every `div` prop.

### SiteFooterWordmark

A giant name that runs edge to edge. With `fit`, the font size is measured so the
word spans the container exactly; the CSS clamp is the no-JS fallback. Hidden from
assistive tech by default (pass `aria-hidden={false}` if it is the only name on the page) and left out
of print.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"solid" \| "muted" \| "outline" \| "fade" \| null` | `"solid"` | `solid` ink, a faint `muted` fill, a hairline `outline`, or a `fade` that dissolves toward the bottom. |
| `fit` | `boolean` | `true` | Scale the text so it spans exactly the container width (measured, and re-measured on resize and font load). |
| `cut` | `boolean` | `false` | Slice the bottom of the letters off at the footer edge. Use it as the footer's last child. |

Also accepts every `div` prop.

## Used in templates

- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)
- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)
- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Site Header

> Sticky header with brand, nav, actions and a full-screen mobile menu. Bar or floating-pill style, optional hide-on-scroll.

Category: Navigation · Registry item: `@portfolio-kit/site-header` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/site-header) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/site-header.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/site-header
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/site-header.tsx` and the kit items it uses: `section`, `use-scroll`.

npm dependencies: `class-variance-authority`, `lucide-react`, `radix-ui`.

## Usage

```tsx
import {
  SiteHeader,
  SiteHeaderActions,
  SiteHeaderBrand,
  SiteHeaderLink,
  SiteHeaderMobile,
  SiteHeaderNav,
} from "@/components/portfolio/site-header"

<SiteHeader>
  <SiteHeaderBrand href="/">Noa Vale</SiteHeaderBrand>
  <SiteHeaderNav>
    <SiteHeaderLink href="/work" active>
      Work
    </SiteHeaderLink>
    <SiteHeaderLink href="/about">About</SiteHeaderLink>
  </SiteHeaderNav>
  <SiteHeaderActions>
    <SiteHeaderMobile>
      <a href="/work">Work</a>
      <a href="/about">About</a>
    </SiteHeaderMobile>
  </SiteHeaderActions>
</SiteHeader>
```

## Examples

### Demo

A sticky bar that turns frosted once you scroll, with a dot on the current page and a full-screen menu on phones.

```tsx
import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  SiteHeader,
  SiteHeaderActions,
  SiteHeaderBrand,
  SiteHeaderLink,
  SiteHeaderMobile,
  SiteHeaderNav,
} from "@/components/portfolio/site-header"
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"
import { typography } from "@/lib/typography"

const links = [
  { label: "Work", href: "#work" },
  { label: "About", href: "#about" },
  { label: "Writing", href: "#writing" },
  { label: "Contact", href: "#contact" },
]

export default function SiteHeaderDemo() {
  return (
    <div className="min-h-[200vh]">
      <a
        href="#main"
        className="fixed top-3 left-3 z-[60] -translate-y-[calc(100%+1rem)] rounded-pill bg-foreground px-4 py-2 text-sm font-medium text-background outline-none focus-visible:translate-y-0 focus-visible:ring-[3px] focus-visible:ring-ring/50"
      >
        Skip to content
      </a>
      <SiteHeader>
        <SiteHeaderBrand href="#top">
          <span className="inline-flex size-7 items-center justify-center rounded-full bg-foreground font-sans text-xs font-medium text-background">
            NV
          </span>
          Noa Vale
        </SiteHeaderBrand>
        <SiteHeaderNav>
          {links.map((link, i) => (
            <SiteHeaderLink key={link.href} href={link.href} active={i === 0}>
              {link.label}
            </SiteHeaderLink>
          ))}
        </SiteHeaderNav>
        <SiteHeaderActions>
          <a href="#contact" className={cn(buttonVariants({ size: "sm" }), "rounded-pill px-4 max-md:hidden")}>
            Let&apos;s talk
          </a>
          <SiteHeaderMobile
            footer={
              <SocialLinks>
                <SocialLink href="https://github.com/example" />
                <SocialLink href="https://www.linkedin.com/in/example" />
                <SocialLink href="https://dribbble.com/example" />
                <SocialLink href="mailto:hello@example.com" />
              </SocialLinks>
            }
          >
            {links.map((link, i) => (
              <a key={link.href} href={link.href} aria-current={i === 0 ? "page" : undefined}>
                {link.label}
              </a>
            ))}
          </SiteHeaderMobile>
        </SiteHeaderActions>
      </SiteHeader>
      <main id="main" className="mx-auto flex max-w-7xl flex-col gap-10 px-5 pt-16 pb-24 sm:px-6 md:px-8 md:pt-24">
        <div className="flex max-w-3xl flex-col gap-5">
          <p className={typography.eyebrow}>Design Engineer · Lisbon</p>
          <h1 className={typography.display}>Calm, fast interfaces.</h1>
          <p className={typography.lead}>Scroll down and the header picks up a border and a frosted background.</p>
        </div>
        <div className="aspect-[16/9] overflow-hidden rounded-2xl border bg-muted">
          <GenerativeArt seed="site-header" variant="interface" />
        </div>
      </main>
    </div>
  )
}
```

### Floating

`variant="floating"` puts the nav in a centered, frosted pill over the page. Suits image-led and single-page portfolios.

```tsx
import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  SiteHeader,
  SiteHeaderActions,
  SiteHeaderBrand,
  SiteHeaderLink,
  SiteHeaderMobile,
  SiteHeaderNav,
} from "@/components/portfolio/site-header"

const links = [
  { label: "Work", href: "#work" },
  { label: "About", href: "#about" },
  { label: "Writing", href: "#writing" },
]

const covers = [
  { seed: "lumen", art: "interface" },
  { seed: "tidewater", art: "landscape" },
  { seed: "fieldnote", art: "bauhaus" },
  { seed: "orbit", art: "interface" },
] as const

export default function SiteHeaderFloating() {
  return (
    <div className="min-h-[200vh]">
      <SiteHeader variant="floating">
        <SiteHeaderBrand href="#top">Noa Vale</SiteHeaderBrand>
        <SiteHeaderNav>
          {links.map((link, i) => (
            <SiteHeaderLink key={link.href} href={link.href} active={i === 0}>
              {link.label}
            </SiteHeaderLink>
          ))}
        </SiteHeaderNav>
        <SiteHeaderActions>
          <a href="#contact" className={cn(buttonVariants({ size: "sm" }), "rounded-pill px-4")}>
            Contact
          </a>
          <SiteHeaderMobile>
            {links.map((link) => (
              <a key={link.href} href={link.href}>
                {link.label}
              </a>
            ))}
          </SiteHeaderMobile>
        </SiteHeaderActions>
      </SiteHeader>
      <main className="mx-auto grid max-w-5xl gap-4 px-5 pt-10 pb-24 sm:grid-cols-2 sm:px-6 md:px-8">
        {covers.map((cover) => (
          <div key={cover.seed} className="aspect-[4/5] overflow-hidden rounded-2xl border bg-muted">
            <GenerativeArt seed={cover.seed} variant={cover.art} />
          </div>
        ))}
      </main>
    </div>
  )
}
```

### Hide on Scroll

`hideOnScroll` slides the header away while you read down and brings it back as soon as you scroll up. Useful for long case studies.

```tsx
import {
  SiteHeader,
  SiteHeaderActions,
  SiteHeaderBrand,
  SiteHeaderLink,
  SiteHeaderMobile,
  SiteHeaderNav,
} from "@/components/portfolio/site-header"
import { typography } from "@/lib/typography"

const links = [
  { label: "Work", href: "#work" },
  { label: "About", href: "#about" },
  { label: "Writing", href: "#writing" },
  { label: "Contact", href: "#contact" },
]

const paragraphs = [
  "Tidewater operators watched forty turbines across six browser tabs. Alarms arrived by email, minutes after the fact, and nobody trusted the numbers on screen.",
  "We shadowed three control-room shifts, then rebuilt the dashboard around a single question: what needs a human right now? Everything else became quiet by default.",
  "Every alarm was sorted into act now, act today or just know — and only the first group was allowed to make noise.",
  "Density stayed high, but hierarchy did the work: numbers you glance at are large, numbers you investigate are one click away.",
  "Color was reserved for things that need attention, so a calm screen really does mean a calm grid.",
  "Median time to acknowledge an alarm fell from nine minutes to under one, and the six tabs became one screen that operators leave open all day.",
]

export default function SiteHeaderHideOnScroll() {
  return (
    <div>
      <SiteHeader hideOnScroll size="sm">
        <SiteHeaderBrand href="#top">Noa Vale</SiteHeaderBrand>
        <SiteHeaderNav>
          {links.map((link, i) => (
            <SiteHeaderLink key={link.href} href={link.href} active={i === 2}>
              {link.label}
            </SiteHeaderLink>
          ))}
        </SiteHeaderNav>
        <SiteHeaderActions className="md:hidden">
          <SiteHeaderMobile>
            {links.map((link) => (
              <a key={link.href} href={link.href}>
                {link.label}
              </a>
            ))}
          </SiteHeaderMobile>
        </SiteHeaderActions>
      </SiteHeader>
      <article className="mx-auto flex max-w-3xl flex-col gap-6 px-5 pt-14 pb-24 sm:px-6 md:px-8">
        <p className={typography.eyebrow}>Case study · Tidewater</p>
        <h1 className={typography.title}>One calm screen for forty turbines</h1>
        <p className={typography.lead}>Scroll down and the header slides away; scroll up a little and it&apos;s back.</p>
        {paragraphs.map((text) => (
          <p key={text} className={typography.lead}>
            {text}
          </p>
        ))}
      </article>
    </div>
  )
}
```

## API Reference

### SiteHeader

The sticky header, a `<header>` landmark. `variant="bar"` is a full-width bar that turns frosted with a hairline
once the page scrolls; `variant="floating"` is a centered pill. Exposes `data-scrolled` / `data-hidden` for your
own styles. Restyle the inner row through `[&_[data-slot=site-header-inner]]:…`.

Sticky positioning keeps it in the flow, so nothing shifts when it starts to stick. It clears the notch
(`env(safe-area-inset-top)`), or leaves that to an `AnnouncementBar` rendered directly before it, and prints without its nav and actions. For keyboard users, put a skip link
before it that appears on focus (see the demo) and give your `<main>` its id.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"bar" \| "floating"` | `"bar"` | `bar`: full-width, gaining a border and blur once the page scrolls. `floating`: a rounded pill that hovers below the top edge. |
| `hideOnScroll` | `boolean` | `false` | Slide the header away while scrolling down; bring it back on scroll up (or when keyboard focus enters it). |
| `size` | `"sm" \| "default" \| "lg" \| "full"` | `"lg"` | Container width of the `bar` variant. Match it to the page's sections. |

Also accepts every `header` prop.

### SiteHeaderBrand

Home link: your name, a wordmark or an avatar + name. Images inside are sized to 28px circles.

Also accepts every `a` prop.

### SiteHeaderNav

The desktop link list, a `<nav>` landmark labelled "Main" (override with `aria-label`). Hidden below `md`
(pair it with `<SiteHeaderMobile>`) and in print. Children are `<SiteHeaderLink>`s.

Also accepts every `nav` prop.

### SiteHeaderLink

A nav link. Renders its own `<li>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | — | Marks the current page: full-strength text, a highlight dot and `aria-current="page"`. |

Also accepts every `a` prop.

### SiteHeaderActions

Right-hand slot for buttons, a theme toggle and `<SiteHeaderMobile>`. Hidden in print.

Also accepts every `div` prop.

### SiteHeaderMobile

Hamburger button (hidden from `md` up) that opens a full-screen menu: a modal dialog that traps focus,
closes on Esc, locks page scroll and returns focus to the button. Pass plain `<a>` elements as children;
the menu closes when one is followed (focus then stays with the page you navigated to) and when the window
widens past `md`. Mark the current page with `aria-current="page"` to tint it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `footer` | `React.ReactNode` | — | Content shown under the links (socials, availability…). |
| `label` | `string` | `"Menu"` | Visible title of the menu sheet. |
| `openLabel` | `string` | ``Open ${label.toLowerCase()}`` | Accessible name of the menu button. Defaults to "Open menu" (from `label`). |
| `closeLabel` | `string` | ``Close ${label.toLowerCase()}`` | Accessible name of the close button. Defaults to "Close menu" (from `label`). |
| `navLabel` | `string` | `"Main"` | Accessible name of the `<nav>` inside the sheet. |
| `open` | `boolean` | — | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | — | Called when the menu opens or closes (button, Esc, following a link, widening past `md`). |

Also accepts every `Dialog.Content` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)
- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md)
- [Not Found](https://www.parthjadhav.com/products/portfolio-kit/templates/not-found.md)
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)
- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Skill Groups

> Skills grouped by discipline, as chips or level bars. Each skill can show a 1–5 level, years of use and an icon.

Category: About · Registry item: `@portfolio-kit/skill-groups` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/skill-groups) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/skill-groups.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/skill-groups
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/skill-groups.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  Skill,
  SkillGroup,
  SkillGroups,
} from "@/components/portfolio/skill-groups"

<SkillGroups>
  <SkillGroup heading="Design" description="From first sketch to design system.">
    <Skill name="Interface design" />
    <Skill name="Prototyping" />
  </SkillGroup>
  <SkillGroup heading="Engineering">
    <Skill name="TypeScript" />
    <Skill name="React" />
  </SkillGroup>
</SkillGroups>
```

## Examples

### Demo

Skills grouped by discipline as quiet chips, each group with an icon and a one-line framing.

```tsx
import { Code2, Palette, PencilRuler } from "lucide-react"

import { Skill, SkillGroup, SkillGroups } from "@/components/portfolio/skill-groups"

const groups = [
  {
    heading: "Design",
    icon: <Palette />,
    description: "From first sketch to a system others can build on.",
    skills: ["Product design", "Design systems", "Prototyping", "Typography"],
  },
  {
    heading: "Engineering",
    icon: <Code2 />,
    description: "Production front-end, fast and accessible.",
    skills: ["TypeScript", "React", "CSS & Tailwind", "Node.js"],
  },
  {
    heading: "Craft",
    icon: <PencilRuler />,
    description: "The details that make an interface feel considered.",
    skills: ["Motion", "Accessibility", "Writing", "Workshops"],
  },
]

export default function SkillGroupsDemo() {
  return (
    <SkillGroups className="mx-auto w-full max-w-5xl">
      {groups.map((group) => (
        <SkillGroup key={group.heading} heading={group.heading} icon={group.icon} description={group.description}>
          {group.skills.map((skill) => (
            <Skill key={skill} name={skill} />
          ))}
        </SkillGroup>
      ))}
    </SkillGroups>
  )
}
```

### With Years

Chips that show years of use, giving context without rating skill on a bar.

```tsx
import { Skill, SkillGroup, SkillGroups } from "@/components/portfolio/skill-groups"

export default function SkillGroupsWithYears() {
  return (
    <SkillGroups columns={2} className="mx-auto w-full max-w-3xl">
      <SkillGroup heading="Languages">
        <Skill name="TypeScript" years={7} />
        <Skill name="CSS" years={9} />
        <Skill name="GLSL" years={1} />
        <Skill name="Python" years={3} />
      </SkillGroup>
      <SkillGroup heading="Tools">
        <Skill name="Figma" years={8} />
        <Skill name="React" years={7} />
        <Skill name="Storybook" years={5} />
        <Skill name="Playwright" years={3} />
      </SkillGroup>
    </SkillGroups>
  )
}
```

### Bars

Rows with a segmented 1–5 level and years of use, for résumé pages where recruiters scan for depth.

```tsx
import { Code2, Palette } from "lucide-react"

import { Skill, SkillGroup, SkillGroups } from "@/components/portfolio/skill-groups"

export default function SkillGroupsBars() {
  return (
    <SkillGroups variant="bars" columns={2} className="mx-auto w-full max-w-3xl">
      <SkillGroup heading="Design" icon={<Palette />}>
        <Skill name="Product design" level={5} years={9} />
        <Skill name="Design systems" level={5} years={6} />
        <Skill name="Prototyping" level={4} years={8} />
        <Skill name="Illustration" level={2} years={3} />
      </SkillGroup>
      <SkillGroup heading="Engineering" icon={<Code2 />}>
        <Skill name="TypeScript" level={5} years={7} />
        <Skill name="React" level={5} years={7} />
        <Skill name="Node.js" level={3} years={5} />
        <Skill name="WebGL" level={2} years={2} />
      </SkillGroup>
    </SkillGroups>
  )
}
```

## API Reference

### SkillGroups

Grid of `SkillGroup`s. Every `Skill` inside follows its `variant`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"chips" \| "bars" \| null` | `"chips"` | `chips`: skills as small pills. `bars`: one row per skill, with its level and years aligned right. |
| `columns` | `1 \| 2 \| 3 \| null` | `3` | Columns from `md` up (3 becomes 2 on tablets). |

Also accepts every `div` prop.

### SkillGroup

A group of `Skill`s under a heading: a `<section>` (unnamed, so not a landmark) with the skills in a list.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `React.ReactNode` | — | Group name, e.g. "Design". Rendered as a heading that labels the group. Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the group name. Use `h4` when the groups sit under an `h3`. |
| `icon` | `React.ReactNode` | — | Small icon in a tile before the heading. Decorative: hidden from screen readers. |
| `description` | `React.ReactNode` | — | One line that frames the group. |

Also accepts every `section` prop.

### Skill

One skill, shown as a chip or a row depending on the `SkillGroups` variant.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `React.ReactNode` | — | The skill, tool or language. |
| `level` | `number` | — | Proficiency from 1 to 5, drawn as a segmented bar and read to screen readers as "level 4 of 5". |
| `levelLabel` | `React.ReactNode` | — | What screen readers hear for the level instead of "level 4 of 5", e.g. "Expert" or a translation. The bar itself is hidden from assistive technology. |
| `years` | `number` | — | Years of use, shown as "6 yrs". |
| `icon` | `React.ReactNode` | — | Small icon or logo before the name. Decorative: hidden from screen readers. |

Also accepts every `li` prop.



---

# Smooth Scroll

> Lenis-powered inertial scrolling for the page or a container, with smooth anchor links and a useLenis() hook. Off under reduced motion; touch stays native.

Category: Effects · Registry item: `@portfolio-kit/smooth-scroll` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/smooth-scroll) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/smooth-scroll.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/smooth-scroll
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/smooth-scroll.tsx` and the kit items it uses: `use-composed-refs`, `use-reduced-motion`.

npm dependencies: `lenis`.

## Usage

```tsx
import { SmoothScroll } from "@/components/portfolio/smooth-scroll"

<SmoothScroll anchorOffset={-64}>
  <main id="top">Your page</main>
</SmoothScroll>
```

## Examples

### Demo

Wrap the page once for inertial scrolling and smooth anchor links; `useLenis().scrollTo` powers a floating back-to-top button, and the reading progress follows the page whether smoothing is on or off.

```tsx
import * as React from "react"
import { ArrowUp } from "lucide-react"

import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  Section,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import { SmoothScroll, useLenis } from "@/components/portfolio/smooth-scroll"
import { useScrollProgress } from "@/hooks/use-scroll-progress"
import { typography } from "@/lib/typography"

const chapters = [
  { id: "work", label: "Work" },
  { id: "about", label: "About" },
  { id: "contact", label: "Contact" },
]

const projects = [
  { slug: "lumen", title: "Lumen", client: "Halcyon Labs" },
  { slug: "tidewater", title: "Tidewater", client: "Tidewater Energy" },
  { slug: "fieldnote", title: "Fieldnote", client: "Fieldnote Inc." },
  { slug: "orbit", title: "Orbit Analytics", client: "Orbit" },
] as const

/**
 * Page progress written straight to the DOM, no re-renders. `useScrollProgress` follows the native
 * scroll, which Lenis drives too, so it keeps working when smoothing is off (reduced motion).
 */
function ProgressBar() {
  const barRef = React.useRef<HTMLSpanElement>(null)
  useScrollProgress((progress) => {
    if (barRef.current) barRef.current.style.transform = `scaleX(${progress})`
  })
  return (
    <span aria-hidden className="absolute inset-x-0 bottom-0 h-0.5 bg-border">
      <span ref={barRef} className="absolute inset-0 origin-left scale-x-0 bg-highlight" />
    </span>
  )
}

/** A floating back-to-top button whose label counts the scroll progress, also written straight to the DOM. */
function BackToTop() {
  const percentRef = React.useRef<HTMLSpanElement>(null)
  const { scrollTo } = useLenis()
  useScrollProgress((progress) => {
    if (percentRef.current) percentRef.current.textContent = `${Math.round(progress * 100)}%`
  })
  return (
    <button
      type="button"
      aria-label="Back to top"
      onClick={() => scrollTo(0)}
      className="fixed right-5 bottom-5 z-40 inline-flex h-11 items-center gap-2 rounded-pill border bg-background/85 pr-5 pl-4 font-mono text-sm tabular-nums shadow-card backdrop-blur-lg outline-none transition-colors duration-200 hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/50 md:right-8 md:bottom-8"
    >
      <ArrowUp aria-hidden className="size-4" />
      <span ref={percentRef} aria-hidden>
        0%
      </span>
    </button>
  )
}

export default function SmoothScrollDemo() {
  return (
    <SmoothScroll>
      <header className="sticky top-0 z-40 border-b bg-background/80 backdrop-blur-lg">
        <div className="mx-auto flex h-14 max-w-6xl items-center justify-between gap-4 px-5 sm:px-6 md:px-8">
          <span className="font-heading text-base">Noa Vale</span>
          <nav aria-label="Chapters">
            <ul role="list" className="flex items-center gap-1">
              {chapters.map((chapter) => (
                <li key={chapter.id}>
                  <a
                    href={`#${chapter.id}`}
                    className="inline-flex h-9 items-center rounded-pill px-3 text-sm font-medium text-muted-foreground outline-none transition-colors duration-200 hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50"
                  >
                    {chapter.label}
                  </a>
                </li>
              ))}
            </ul>
          </nav>
        </div>
        <ProgressBar />
      </header>

      <main>
        <Section spacing="lg">
          <p className={typography.meta}>Scroll, or jump with the links above</p>
          <h1 className={cn(typography.display, "mt-6 max-w-4xl")}>Scrolling with a little weight to it.</h1>
        </Section>

        <Section id="work" divider>
          <SectionHeader>
            <SectionEyebrow index={1}>Work</SectionEyebrow>
            <SectionTitle>Selected projects</SectionTitle>
          </SectionHeader>
          <ul role="list" className="mt-12 grid gap-4 sm:grid-cols-2">
            {projects.map((project) => (
              <li key={project.slug} className="overflow-hidden rounded-2xl border bg-card shadow-card">
                <div className="aspect-[16/10] border-b">
                  <GenerativeArt seed={project.slug} variant="interface" />
                </div>
                <div className="flex flex-col gap-1 p-5 md:p-6">
                  <p className={typography.meta}>{project.client}</p>
                  <h3 className={typography.heading}>{project.title}</h3>
                </div>
              </li>
            ))}
          </ul>
        </Section>

        <Section id="about" divider>
          <SectionHeader>
            <SectionEyebrow index={2}>About</SectionEyebrow>
            <SectionTitle>Nine years between design and code.</SectionTitle>
            <SectionDescription>
              I work at the seam between product design and front-end engineering, helping startups and studios turn
              rough ideas into interfaces that feel inevitable.
            </SectionDescription>
          </SectionHeader>
        </Section>

        <Section id="contact" divider className="min-h-[70svh]">
          <SectionHeader>
            <SectionEyebrow index={3}>Contact</SectionEyebrow>
            <SectionTitle>Say hello.</SectionTitle>
            <SectionDescription>hello@example.com</SectionDescription>
          </SectionHeader>
        </Section>
      </main>
      <BackToTop />
    </SmoothScroll>
  )
}
```

### Scroll container

`root={false}` smooths one panel instead of the page, like a changelog or a long list inside a card. At either end the wheel passes back to the page.

```tsx
import { cn } from "@/lib/utils"
import { SmoothScroll } from "@/components/portfolio/smooth-scroll"
import { typography } from "@/lib/typography"

const releases = [
  { version: "3.4", date: "2025-10-02", title: "Theme-aware generative covers", body: "Artwork now follows the active theme's palette." },
  { version: "3.3", date: "2025-09-12", title: "Reduced-motion audit", body: "Every effect settles instantly when motion is reduced." },
  { version: "3.2", date: "2025-08-21", title: "Faster first paint", body: "Fonts are preloaded and the hero no longer waits on images." },
  { version: "3.1", date: "2025-07-30", title: "Keyboard-first command menu", body: "Jump to any project or post with ⌘K." },
  { version: "3.0", date: "2025-07-01", title: "A new design system", body: "Tokens, components and docs rebuilt from scratch." },
  { version: "2.9", date: "2025-05-18", title: "Case-study templates", body: "Long-form project pages with sticky chapters." },
  { version: "2.8", date: "2025-04-09", title: "RSS and newsletter", body: "Every post is now available by feed or email." },
]

const formatDate = (iso: string) =>
  new Date(iso).toLocaleDateString("en-US", { month: "short", day: "numeric", timeZone: "UTC" })

export default function SmoothScrollContainer() {
  return (
    <div className="w-full max-w-lg overflow-hidden rounded-2xl border bg-card shadow-card">
      <div className="flex items-center justify-between gap-4 border-b px-5 py-3 md:px-6">
        <span className={typography.eyebrow}>Changelog</span>
        <span className={typography.meta}>Scroll inside ↓</span>
      </div>
      <SmoothScroll
        root={false}
        tabIndex={0}
        aria-label="Changelog"
        className="h-[24rem] outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:ring-inset"
      >
        <ol role="list">
          {releases.map((release) => (
            <li key={release.version} className="flex gap-5 border-b px-5 py-5 last:border-b-0 md:px-6">
              <span className={cn(typography.meta, "w-10 shrink-0 pt-1")}>v{release.version}</span>
              <div className="flex flex-col gap-1">
                <time dateTime={release.date} className={typography.meta}>
                  {formatDate(release.date)}
                </time>
                <h3 className={typography.heading}>{release.title}</h3>
                <p className={typography.body}>{release.body}</p>
              </div>
            </li>
          ))}
        </ol>
      </SmoothScroll>
    </div>
  )
}
```

### Horizontal gallery

`orientation="horizontal"` turns the mouse wheel into a smooth sideways glide through a strip of project covers. At either end, the wheel scrolls the page again.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { SmoothScroll } from "@/components/portfolio/smooth-scroll"
import { typography } from "@/lib/typography"

const projects = [
  { slug: "lumen", title: "Lumen", year: 2025 },
  { slug: "tidewater", title: "Tidewater", year: 2025 },
  { slug: "fieldnote", title: "Fieldnote", year: 2024 },
  { slug: "orbit", title: "Orbit Analytics", year: 2024 },
  { slug: "kiln", title: "Kiln", year: 2023 },
] as const

export default function SmoothScrollHorizontal() {
  return (
    <div className="mx-auto flex max-w-5xl flex-col gap-4">
      <div className="flex items-baseline justify-between gap-4">
        <h2 className={typography.heading}>Recent work</h2>
        <p className={typography.meta}>Scroll to glide sideways →</p>
      </div>
      <SmoothScroll
        root={false}
        orientation="horizontal"
        tabIndex={0}
        aria-label="Recent work"
        className="-mx-1 scroll-px-1 rounded-2xl pb-3 outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
      >
        {/* p-1 leaves room for the cards' focus rings inside the scroller. */}
        <ul role="list" className="flex gap-4 p-1">
          {projects.map((project) => (
            <li key={project.slug} className="w-56 shrink-0 sm:w-64">
              <a
                href={`#${project.slug}`}
                className="group flex flex-col gap-3 rounded-2xl outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
              >
                <span className="block aspect-[4/5] overflow-hidden rounded-2xl border">
                  <GenerativeArt
                    seed={project.slug}
                    variant="interface"
                    className="transition-transform duration-700 ease-smooth motion-reduce:transition-none [@media(hover:hover)]:group-hover:scale-[1.04]"
                  />
                </span>
                <span className="flex items-baseline justify-between gap-3 px-1">
                  <span className={typography.heading}>{project.title}</span>
                  <span className={typography.meta}>{project.year}</span>
                </span>
              </a>
            </li>
          ))}
        </ul>
      </SmoothScroll>
    </div>
  )
}
```

## API Reference

### SmoothScroll

Wrap your app (or a scroll area with `root={false}`). Lenis is created on mount, destroyed on
unmount, and never created when the user prefers reduced motion: smoothed scrolling moves the
page further and longer than the visitor asked, which can trigger motion sickness, so use it
sparingly and keep the default `lerp`.

Only the mouse wheel and trackpad are smoothed. Touch keeps native momentum (unless `syncTouch`),
and the keyboard (Space, Page Up/Down, arrows, Home/End), find-in-page, focus moving to an
off-screen element and the scrollbar all scroll natively; a glide still running stops so it can't
pull the page back. While a dialog or menu locks the page (`overflow: hidden` on `<html>` or
`<body>`, as Radix dialogs do), the wheel is left to the browser, and inner scroll areas (a
dialog body, a code block) scroll on their own. Add `data-lenis-prevent` to keep any other
element native (a map, a canvas).

A container (`root={false}`) is keyboard-scrollable only when it can take focus: give it
`tabIndex={0}` and an `aria-label` unless it holds focusable content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `true` | Turn smoothing off without unmounting (native scroll takes over). |
| `root` | `boolean` | `true` | Smooth the whole page (window) and render no element of its own — `className` and other props are ignored. `false` renders a scrollable container instead (give it a height). |
| `lerp` | `number` | `0.1` | Interpolation per frame, 0–1. Lower is floatier. Ignored when `duration` is set. |
| `duration` | `number` | — | Fixed scroll animation duration in seconds (uses Lenis' expo easing). |
| `wheelMultiplier` | `number` | `1` | Scales mouse-wheel distance. Above `1` scrolls further per notch. |
| `touchMultiplier` | `number` | `1` | Scales touch distance (only with `syncTouch`). |
| `syncTouch` | `boolean` | `false` | Also smooth touch scrolling. Native touch momentum is usually better; off by default. |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Scroll axis. `horizontal` (with `root={false}`) maps the vertical wheel onto a sideways glide; at either end the wheel is handed back to the page, so the strip never traps scrolling. |
| `anchors` | `boolean` | `true` | Scroll same-page `href="#id"` links smoothly. The browser still updates the URL and moves the keyboard starting point to the target, as with a plain jump. In a container, only links to targets inside it are handled. |
| `anchorOffset` | `number` | `0` | Extra offset for anchor targets, e.g. `-80` for a sticky header. Targets' `scroll-margin-top` is already honored (kit `<Section>` has `scroll-mt-24`). |
| `options` | `Omit<LenisOptions, "wrapper" \| "content" \| "eventsTarget">` | — | Any other Lenis option. |

Also accepts every `div` prop.

## Used in templates

- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)



---

# Social Links

> Profile links as icons, pills or text. Pass URLs and the brand icon and label are detected automatically.

Category: Contact · Registry item: `@portfolio-kit/social-links` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/social-links) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/social-links.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/social-links
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/social-links.tsx` and the kit items it uses: `brand-icons`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  SocialLink,
  SocialLinks,
} from "@/components/portfolio/social-links"

<SocialLinks>
  <SocialLink href="https://github.com/example" />
  <SocialLink href="https://www.linkedin.com/in/example" />
  <SocialLink href="mailto:hello@example.com" />
</SocialLinks>
```

## Examples

### Demo

Pass your profile URLs. Each link gets its brand icon and an accessible name.

```tsx
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"
import { typography } from "@/lib/typography"

const profiles = [
  "https://github.com/example",
  "https://x.com/example",
  "https://www.linkedin.com/in/example",
  "https://dribbble.com/example",
  "mailto:hello@example.com",
]

export default function SocialLinksDemo() {
  return (
    <div className="flex flex-col items-center gap-3">
      <p id="elsewhere" className={typography.eyebrow}>
        Find me elsewhere
      </p>
      <SocialLinks aria-labelledby="elsewhere">
        {profiles.map((href) => (
          <SocialLink key={href} href={href} />
        ))}
      </SocialLinks>
    </div>
  )
}
```

### Pills

Icon and name in a bordered pill. Easier to scan when the links are the main call to action.

```tsx
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"

const profiles = [
  "https://github.com/example",
  "https://www.linkedin.com/in/example",
  "https://dribbble.com/example",
  "https://read.cv/example",
]

export default function SocialLinksPills() {
  return (
    <SocialLinks variant="pill" className="max-w-lg justify-center">
      {profiles.map((href) => (
        <SocialLink key={href} href={href} />
      ))}
    </SocialLinks>
  )
}
```

### Text

Plain labels with a ↗ arrow, for footers and “Elsewhere” lists.

```tsx
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"
import { typography } from "@/lib/typography"

export default function SocialLinksText() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <p id="elsewhere" className={typography.eyebrow}>
        Elsewhere
      </p>
      <SocialLinks variant="text" aria-labelledby="elsewhere">
        <SocialLink href="https://github.com/example" />
        <SocialLink href="https://www.linkedin.com/in/example" />
        <SocialLink href="https://bsky.app/profile/example.com" />
        <SocialLink href="https://example.substack.com" />
      </SocialLinks>
    </div>
  )
}
```

### Custom Links

Override the detected `label`, or pass your own `icon` for sites without a built-in brand, such as a newsletter or a shop.

```tsx
import { BookOpen, Newspaper, ShoppingBag } from "lucide-react"

import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"

export default function SocialLinksCustom() {
  return (
    <SocialLinks variant="pill" aria-label="Elsewhere" className="max-w-lg justify-center">
      <SocialLink href="https://github.com/example" label="Open source" />
      <SocialLink href="https://notes.example.com" label="Notes" icon={<BookOpen aria-hidden />} />
      <SocialLink href="https://letters.example.com" label="Newsletter" icon={<Newspaper aria-hidden />} />
      <SocialLink href="https://shop.example.com" label="Print shop" icon={<ShoppingBag aria-hidden />} />
    </SocialLinks>
  )
}
```

## API Reference

### SocialLinks

The list. `icon` (default) shows brand icons with accessible names, `pill` adds the name in a bordered chip,
`text` is plain labels with a ↗ arrow. Labelled "Social links" for assistive tech; pass `aria-label` or
`aria-labelledby` (pointing at a visible heading) to change it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"icon" \| "pill" \| "text" \| null` | `"icon"` | `icon`: brand icons only. `pill`: icon + name in a bordered chip. `text`: name + ↗, no icon. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added to links that open in a new tab. Translate it for non-English sites. |

Also accepts every `ul` prop.

### SocialLink

One profile link. Must be a direct child of `<SocialLinks>` (it renders its own `<li>`). External links open in a
new tab with `rel="me"` and say so to screen readers; the `text` style also shows a ↗. Icon-only links are named
by `label` (the brand name), shown as a tooltip too.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` (required) | `string` | — | Profile URL, `mailto:` or `tel:` link. The brand icon and name are detected from it. |
| `brand` | `BrandName` | — | Override the detected brand, e.g. for a custom domain. |
| `label` | `string` | — | Visible label for pill/text variants and the accessible name for icons. Defaults to the brand name or host. |
| `icon` | `React.ReactNode` | — | Custom icon (e.g. a lucide icon with `aria-hidden`) when the brand isn't built in. |
| `newTabLabel` | `string` | — | Screen-reader text for a link that opens in a new tab. Defaults to the list's `newTabLabel`. |

Also accepts every `a` prop.

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)
- [Creative Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/creative.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)
- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Links](https://www.parthjadhav.com/products/portfolio-kit/templates/links.md)
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md)
- [Photographer](https://www.parthjadhav.com/products/portfolio-kit/templates/photographer.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Social Post

> A post from a social network as a card: author, handle, network icon, date, text with linked mentions, tags and URLs, optional media and reply/repost/like counts.

Category: Social Proof · Registry item: `@portfolio-kit/social-post` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/social-post) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/social-post.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/social-post
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/social-post.tsx` and the kit items it uses: `brand-icons`, `format`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import {
  SocialPost,
  SocialPostFooter,
  SocialPostHeader,
  SocialPostText,
} from "@/components/portfolio/social-post"

<SocialPost href="https://example.com/posts/3kq2" network="bluesky">
  <SocialPostHeader name="Ines Carvalho" handle="ines.example.com" date="2026-02-12T09:30:00Z" />
  <SocialPostText>Shipped our new checkout with Noa this week. Conversion is up 18%.</SocialPostText>
  <SocialPostFooter replies={24} reposts={61} likes={1280} />
</SocialPost>
```

## Examples

### Demo

A public post about your work, shown as social proof: author, network, date, linked mentions and tags, counts and a link to the original.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  SocialPost,
  SocialPostFooter,
  SocialPostHeader,
  SocialPostText,
} from "@/components/portfolio/social-post"

export default function SocialPostDemo() {
  return (
    <SocialPost
      href="https://example.com/posts/3kq2"
      network="bluesky"
      mentionHref={(handle) => `https://example.com/profile/${handle}`}
      tagHref={(tag) => `https://example.com/search?q=%23${tag}`}
      className="w-full max-w-md"
    >
      <SocialPostHeader
        name="Ines Carvalho"
        handle="ines.example.com"
        avatar={<GenerativeArt seed="Ines Carvalho" variant="portrait" grain={false} />}
        date="2026-02-12T09:30:00Z"
      />
      <SocialPostText>
        {`Shipped our new checkout with @noa.example.com this week. Conversion is up 18% and the codebase is somehow smaller than before.

If you need someone who sweats the details and still ships on time, hire Noa. #designengineering`}
      </SocialPostText>
      <SocialPostFooter replies={24} reposts={61} likes={1280} />
    </SocialPost>
  )
}
```

### Wall

A masonry wall of posts from different networks using CSS columns, for a "What people say" section. Mixed lengths and one post with an image.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import type { BrandName } from "@/components/portfolio/brand-icons"
import {
  SocialPost,
  SocialPostFooter,
  SocialPostHeader,
  SocialPostMedia,
  SocialPostText,
} from "@/components/portfolio/social-post"

type Post = {
  id: string
  network: BrandName
  name: string
  handle: string
  date: string
  text: string
  likes: number
  reposts?: number
  replies?: number
  media?: boolean
}

const posts: Post[] = [
  {
    id: "p1",
    network: "bluesky",
    name: "Ines Carvalho",
    handle: "ines.example.com",
    date: "2026-02-12T09:30:00Z",
    text: "Shipped our new checkout with @noa.example.com. Conversion up 18%, codebase smaller than before.",
    likes: 1280,
    reposts: 61,
    replies: 24,
  },
  {
    id: "p2",
    network: "mastodon",
    name: "Tomas Reyes",
    handle: "tomas@example.com",
    date: "2026-01-28T17:05:00Z",
    text: "The Fieldnote site loads in under a second on a train in the mountains. That's the whole review. #webperf",
    likes: 342,
    reposts: 88,
  },
  {
    id: "p3",
    network: "linkedin",
    name: "Priya Anand",
    handle: "priya-anand",
    date: "2026-01-15T08:00:00Z",
    text: "We brought Noa in for a two-week sprint on our design system. We left with tokens our engineers actually use, a component library with docs, and a team that finally agrees on what \"primary\" means.\n\nRare to find someone equally at home in Figma and in a pull request.",
    likes: 214,
    replies: 19,
    media: true,
  },
  {
    id: "p4",
    network: "threads",
    name: "Sam Okafor",
    handle: "sam.makes",
    date: "2025-12-03T20:12:00Z",
    text: "New shop is live and it finally looks like the pots. Thank you @noa.vale 🙏 example.com/kiln",
    likes: 96,
  },
]

export default function SocialPostWall() {
  return (
    <div className="mx-auto max-w-5xl columns-1 gap-4 sm:columns-2 lg:columns-3 [&>*]:mb-4 [&>*]:break-inside-avoid">
      {posts.map((post) => (
        <SocialPost key={post.id} href={`https://example.com/posts/${post.id}`} network={post.network}>
          <SocialPostHeader
            name={post.name}
            handle={post.handle}
            date={post.date}
            avatar={<GenerativeArt seed={post.name} variant="portrait" grain={false} />}
          />
          <SocialPostText>{post.text}</SocialPostText>
          {post.media && (
            <SocialPostMedia>
              <GenerativeArt seed={`${post.id}-media`} variant="interface" label="Screenshot of the design system's documentation site" />
            </SocialPostMedia>
          )}
          <SocialPostFooter replies={post.replies} reposts={post.reposts} likes={post.likes} />
        </SocialPost>
      ))}
    </div>
  )
}
```

## API Reference

### SocialPost

The card, an `<article>` named by the author's name in `SocialPostHeader` (pass `aria-label` to
name it yourself). Compose `SocialPostHeader`, `SocialPostText`, an optional `SocialPostMedia` and
`SocialPostFooter` inside. Links inside the post (mentions, URLs, the original) stay separate
links, so the card itself isn't one big link. External links open in a new tab and say so to screen readers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | URL of the original post. The date and the "View on …" link point to it. |
| `network` | `BrandName` | — | The network it was posted on, e.g. `"bluesky"`, `"mastodon"`, `"linkedin"`, `"x"`, `"threads"`. Sets the icon and the link label. |
| `mentionHref` | `(handle: string) => string \| undefined` | — | Where an `@mention` in `SocialPostText` links to, e.g. `(h) => \`https://bsky.app/profile/${h}\``. Return `undefined` to leave it as text. |
| `tagHref` | `(tag: string) => string \| undefined` | — | Where a `#tag` in `SocialPostText` links to. Return `undefined` to leave it as text. |
| `locale` | `string` | `"en-US"` | Locale for the date and the counts, e.g. `"de-DE"`. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | What screen readers hear after every link in the post that opens in a new tab. |

Also accepts every `article` prop.

### SocialPostHeader

Avatar, name, handle, date and the network icon. The date links to the original post when the card has `href`.
Long names and handles wrap instead of being cut off. The network icon is named in text for screen readers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Display name. |
| `handle` | `string` | — | Handle without or with the leading `@`, e.g. `"noa.example.com"`. |
| `avatar` | `string \| React.ReactNode` | — | Image URL or node (e.g. `<GenerativeArt variant="portrait" />`). Falls back to initials. |
| `date` | `string \| Date` | — | When it was posted. ISO strings render as `<time>` (formatted with the card's `locale`); other strings are shown as-is ("2h"). |
| `profileHref` | `string` | — | Profile URL. Makes the name a link. |
| `originalLabel` | `string` | `"original post"` | What screen readers hear after the date when it links to the original post. |

Also accepts every `header` prop.

### SocialPostText

The post's text. Pass a string and blank lines become paragraphs, URLs become links and `@mentions` and
`#tags` are highlighted (and linked when the card has `mentionHref` / `tagHref`). Pass JSX to control it yourself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `linkify` | `boolean` | `true` | Link `@mentions`, `#tags` and URLs in string content (mentions and tags use the card's `mentionHref` / `tagHref`). |

Also accepts every `div` prop.

### SocialPostMedia

Attached media. Put an `<img>` (cropped to fill, give it `alt`) or `<GenerativeArt />` inside. The 16:10 box is
reserved before the image loads, so nothing jumps; change it with `className`, e.g. `aspect-video`.

Also accepts every `div` prop.

### SocialPostFooter

Counts (compact, e.g. "1.2K"; screen readers hear the full number) and a link to the original post.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `replies` | `number` | — | Number of replies. Omit to hide. |
| `reposts` | `number` | — | Number of reposts / boosts / shares. Omit to hide. |
| `likes` | `number` | — | Number of likes. Omit to hide. |
| `linkLabel` | `React.ReactNode \| false` | — | Label of the link to the original. Defaults to "View on <network>" (or "View post"); `false` hides it. |
| `statsLabel` | `string` | `"Engagement"` | Accessible name of the list of counts. |
| `statLabel` | `(count: string, stat: "replies" \| "reposts" \| "likes", value: number) => string` | `defaultStatLabel` | What screen readers hear for each count, given the full number (already formatted for the card's `locale`, e.g. "1,280") and which count it is. Defaults to English: "1,280 likes". |
| `newTabLabel` | `string` | — | What screen readers hear after the link when it opens in a new tab. Defaults to the card's `newTabLabel`. |

Also accepts every `footer` prop.



---

# Sound Toggle

> A "Sound — On/Off" toggle button with equalizer bars for sites with ambient audio or UI sounds: off by default, remembered, and readable anywhere through `useSound()`.

Category: Utilities · Registry item: `@portfolio-kit/sound-toggle` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/sound-toggle) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/sound-toggle.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/sound-toggle
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/sound-toggle.tsx`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  SoundToggle,
  SoundToggleBars,
  SoundToggleLabel,
} from "@/components/portfolio/sound-toggle"

<SoundToggle>
  <SoundToggleBars />
  <SoundToggleLabel />
</SoundToggle>
```

## Examples

### Demo

Ambient audio for a sound designer's site: off until the visitor presses "Sound", then a quiet loop plays, and the choice is remembered for the next visit.

```tsx
import * as React from "react"

import { SoundToggle, getSoundPreference, useSound } from "@/components/portfolio/sound-toggle"
import { typography } from "@/lib/typography"

export default function SoundToggleDemo() {
  const audioRef = React.useRef<HTMLAudioElement>(null)
  const { enabled } = useSound()
  const [waiting, setWaiting] = React.useState(false)

  // Follow the preference. A remembered "on" can't start by itself: browsers block sound until the
  // visitor interacts with the page, so wait for their first click or key press.
  React.useEffect(() => {
    const audio = audioRef.current
    if (!audio) return
    if (!enabled) {
      audio.pause()
      return
    }
    if (!audio.paused) return
    let active = true
    const start = () => {
      if (!getSoundPreference()) return
      audio.play().catch(() => {})
    }
    audio.play().catch(() => {
      if (!active) return
      setWaiting(true)
      document.addEventListener("click", start, { once: true })
      document.addEventListener("keydown", start, { once: true })
    })
    return () => {
      active = false
      document.removeEventListener("click", start)
      document.removeEventListener("keydown", start)
    }
  }, [enabled])

  return (
    <div className="flex flex-col items-center gap-4 text-center">
      {/* Your files: in public/ ("/audio/ambient.mp3"). Keep it short, quiet and seamless; it loops. The
          captions file describes the sound for people who can't hear it; for a wordless loop one cue is enough:
          WEBVTT, a blank line, "00:00:00.000 --> 00:00:09.000", then "[Soft ambient tones]". */}
      <audio ref={audioRef} src="media/low-tide.mp3" loop preload="none" onPlay={() => setWaiting(false)}>
        <track kind="captions" src="media/low-tide.vtt" srcLang="en" label="English" default />
      </audio>
      <SoundToggle
        // Start inside the click itself: Safari only allows play() during the gesture.
        onPressedChange={(on) => {
          const audio = audioRef.current
          if (!audio) return
          if (on) {
            audio.volume = 0.6
            audio.play().catch(() => {})
          } else audio.pause()
        }}
      />
      <p className={typography.meta} aria-live="polite">
        {enabled && waiting
          ? "Audio is paused. Press anywhere to play."
          : enabled
            ? "Now playing: Low Tide, ambient loop"
            : "Ambient score by Ines Morrow"}
      </p>
    </div>
  )
}
```

### In a Header

An icon toggle beside the nav that turns soft UI clicks on and off; the links read the same preference with `useSound()`.

```tsx
import { cn } from "@/lib/utils"
import { SoundToggle, useSound } from "@/components/portfolio/sound-toggle"
import { typography } from "@/lib/typography"

const links = [
  { label: "Work", href: "#work" },
  { label: "Lab", href: "#lab" },
  { label: "About", href: "#about" },
]

// Kept apart from ambient music ("sound"): visitors often want one without the other.
let context: AudioContext | null = null

/** A 70 ms tick, synthesized so there's no file to load. Call it from a click: that's the gesture browsers need. */
function tick() {
  context ??= new AudioContext()
  const now = context.currentTime
  const tone = context.createOscillator()
  const gain = context.createGain()
  tone.frequency.value = 1320
  gain.gain.setValueAtTime(0.05, now)
  gain.gain.exponentialRampToValueAtTime(0.0001, now + 0.07)
  tone.connect(gain).connect(context.destination)
  tone.start(now)
  tone.stop(now + 0.08)
}

export default function SoundToggleInHeader() {
  const { enabled } = useSound({ storageKey: "ui-sounds" })

  return (
    <div>
      <header className="flex h-16 items-center justify-between gap-4 border-b px-5 sm:gap-6 md:px-8">
        <a
          href="#top"
          className="rounded-md font-heading text-base outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
        >
          Kai Okafor
        </a>
        <div className="flex items-center gap-1">
          <nav aria-label="Main">
            <ul role="list" className="flex items-center gap-1">
              {links.map((link) => (
                <li key={link.href}>
                  <a
                    href={link.href}
                    onClick={() => enabled && tick()}
                    className="inline-flex h-9 items-center rounded-pill px-2 text-sm sm:px-3 font-medium text-muted-foreground outline-none transition-colors hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50"
                  >
                    {link.label}
                  </a>
                </li>
              ))}
            </ul>
          </nav>
          <SoundToggle
            variant="icon"
            label="Interface sounds"
            storageKey="ui-sounds"
            onPressedChange={(on) => on && tick()}
          />
        </div>
      </header>
      <main className="flex flex-col gap-4 px-5 py-14 md:px-8">
        <p className={typography.eyebrow}>Creative developer</p>
        <h1 className={cn(typography.title, "max-w-2xl")}>Turn sound on, then click around the nav.</h1>
      </main>
    </div>
  )
}
```

### Text Only

A mono "Sound: Off" switch in the footer, next to the other small print, for minimal sites that avoid icons.

```tsx
import { SoundToggle } from "@/components/portfolio/sound-toggle"
import { typography } from "@/lib/typography"

export default function SoundToggleTextOnly() {
  return (
    <div className="flex min-h-[220px] flex-col justify-end">
      <footer className="flex flex-wrap items-center justify-between gap-x-6 gap-y-3 border-t px-5 py-5 md:px-8">
        <p className={typography.meta}>© 2026 Ines Morrow · Sound design</p>
        <div className="flex items-center gap-5">
          <a
            href="mailto:ines@example.com"
            className="inline-flex min-h-6 items-center rounded-sm font-mono text-[0.6875rem] tracking-[0.08em] text-muted-foreground uppercase outline-none hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50"
          >
            Email
          </a>
          <SoundToggle variant="text" />
        </div>
      </footer>
    </div>
  )
}
```

## API Reference

### SoundToggle

A toggle button (`aria-pressed`) that remembers whether the visitor wants sound. It plays nothing
itself: read the state with `useSound()`, `onPressedChange` or the `sound-change` window event.
With no children it renders `SoundToggleBars` and, except for `icon`, `SoundToggleLabel`.
`data-state` is `on` or `off`.

Browsers only let a page start audio from a visitor's gesture. Call `audio.play()` inside
`onPressedChange` (Safari refuses it later), and when a remembered "on" is restored on a new visit,
wait for the first click or key press before playing (the demo shows how). The server renders
"off"; a remembered "on" appears once the page hydrates, without animating.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"outline" \| "ghost" \| "icon" \| "text"` | `"outline"` | `outline`: bordered pill. `ghost`: no border until hovered, for headers. `icon`: bars only (36px; 44px on touch screens). `text`: a mono "Sound: Off" link-style label for footers. |
| `pressed` | `boolean` | — | Controlled state. When set, the toggle never reads or writes storage. |
| `defaultPressed` | `boolean` | `false` | Initial state when nothing is saved (uncontrolled). Keep it `false`: never start sound unasked. |
| `onPressedChange` | `(pressed: boolean) => void` | — | Called inside the click with the new state, so you can call `audio.play()` within the gesture. |
| `storageKey` | `string` | — | localStorage key for the saved choice (uncontrolled). Toggles and `useSound()` sharing a key stay in sync. |
| `label` | `string` | `"Sound"` | Accessible and visible name (also the `icon` variant's tooltip). It stays the same; `aria-pressed` carries on/off. To translate the visible "On"/"Off", compose the parts: `<SoundToggle label="Ton"><SoundToggleBars /><SoundToggleLabel on="An" off="Aus" /></SoundToggle>`. |

Also accepts every `button` prop.

### SoundToggleBars

Four bars: flat when off and a still equalizer shape when on. After a press turns sound on they
bounce for about four seconds, then settle; they stay still under reduced motion. Decorative
(`aria-hidden`).

Also accepts every `span` prop.

### SoundToggleLabel

The visible "Sound — Off" text. The label is the button's name; the state word is hidden from
assistive tech because `aria-pressed` already announces it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `on` | `string` | `"On"` | Text for the on state. |
| `off` | `string` | `"Off"` | Text for the off state. |
| `separator` | `string` | `" — "` | Between the label and the state. |

Also accepts every `span` prop.



---

# Spotlight Card

> Card with a soft glow that follows the pointer and a brighter rim on its border. Wrap cards in a group so one pointer lights the borders across a grid.

Category: Effects · Registry item: `@portfolio-kit/spotlight-card` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/spotlight-card) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/spotlight-card.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/spotlight-card
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/spotlight-card.tsx` and the kit items it uses: `use-composed-refs`.

## Usage

```tsx
import {
  SpotlightCard,
  SpotlightGroup,
} from "@/components/portfolio/spotlight-card"

<SpotlightGroup>
  <SpotlightCard className="p-6">
    <h3>Motion &amp; interaction</h3>
    <p>Purposeful transitions that feel inevitable.</p>
  </SpotlightCard>
  <SpotlightCard className="p-6">
    <h3>Design systems</h3>
    <p>Tokens and components your team will use.</p>
  </SpotlightCard>
</SpotlightGroup>
```

## Examples

### Demo

A service card on a dark surface, with a soft glow that follows the pointer and a brighter rim light along its border.

```tsx
import { MousePointerClick } from "lucide-react"

import { cn } from "@/lib/utils"
import { SpotlightCard } from "@/components/portfolio/spotlight-card"
import { typography } from "@/lib/typography"

export default function SpotlightCardDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-6">
      {/* `dark` gives the card the theme's dark palette, where the glow reads best. */}
      <SpotlightCard size={300} color="var(--highlight-ink)" className="dark flex w-full flex-col gap-10 p-5 md:p-6">
        <div className="flex items-start justify-between">
          <span className="inline-flex size-10 items-center justify-center rounded-xl border bg-background">
            <MousePointerClick aria-hidden className="size-[1.1rem]" />
          </span>
          <span className={cn(typography.meta, "text-highlight-ink")}>04</span>
        </div>
        <div className="flex flex-col gap-2">
          <h3 className={typography.heading}>Motion &amp; interaction</h3>
          <p className={typography.body}>Purposeful transitions and micro-interactions that feel inevitable.</p>
        </div>
      </SpotlightCard>
      <p className={typography.meta}>Move your pointer over the card</p>
    </div>
  )
}
```

### Group

Wrap a grid in `SpotlightGroup` and one pointer lights the rims of every nearby card, so the light carries across the gaps.

```tsx
import { Code2, Layers, MousePointerClick, PenTool } from "lucide-react"

import { cn } from "@/lib/utils"
import { SpotlightCard, SpotlightGroup } from "@/components/portfolio/spotlight-card"
import { typography } from "@/lib/typography"

const services = [
  { icon: PenTool, title: "Product design", body: "From fuzzy idea to tested flows, wireframes and a polished UI kit." },
  { icon: Code2, title: "Front-end engineering", body: "Accessible, fast React and TypeScript that your team can own." },
  { icon: Layers, title: "Design systems", body: "Tokens, components and docs that keep eleven products consistent." },
  { icon: MousePointerClick, title: "Motion & interaction", body: "Purposeful transitions and micro-interactions that feel inevitable." },
]

export default function SpotlightCardGroup() {
  return (
    <div className="mx-auto flex max-w-4xl flex-col gap-6">
      <p className={typography.meta}>Move your pointer across the grid</p>
      <SpotlightGroup className="grid gap-4 sm:grid-cols-2">
        {services.map((service, i) => (
          <SpotlightCard key={service.title} className="flex flex-col gap-10 p-5 md:p-6">
            <div className="flex items-start justify-between">
              <span className="inline-flex size-10 items-center justify-center rounded-xl border bg-background">
                <service.icon aria-hidden className="size-[1.1rem]" />
              </span>
              <span className={cn(typography.meta, "text-highlight-ink")}>{String(i + 1).padStart(2, "0")}</span>
            </div>
            <div className="flex flex-col gap-2">
              <h3 className={typography.heading}>{service.title}</h3>
              <p className={typography.body}>{service.body}</p>
            </div>
          </SpotlightCard>
        ))}
      </SpotlightGroup>
    </div>
  )
}
```

### Custom color

Pass any CSS color to `color` (here the `success` token for an availability card) and a smaller `size` for a tighter glow.

```tsx
import { ArrowRight } from "lucide-react"

import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import { StatusDot } from "@/components/portfolio/availability-badge"
import { SpotlightCard } from "@/components/portfolio/spotlight-card"
import { typography } from "@/lib/typography"

export default function SpotlightCardCustomColor() {
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-6">
      <SpotlightCard color="var(--success)" size={320} className="flex w-full flex-col gap-8 p-5 md:p-6">
        <p className={cn(typography.eyebrow, "inline-flex items-center gap-2.5")}>
          <StatusDot />
          Available from March
        </p>
        <div className="flex flex-col gap-2">
          <h3 className={typography.heading}>One project slot open for spring</h3>
          <p className={typography.body}>
            Six to ten weeks, design through build. Best for product teams shipping something new.
          </p>
        </div>
        <a href="#contact" className={buttonVariants({ className: "w-fit rounded-pill" })}>
          Book an intro call
          <ArrowRight aria-hidden />
        </a>
      </SpotlightCard>
      <p className={typography.meta}>Move your pointer over the card</p>
    </div>
  )
}
```

## API Reference

### SpotlightCard

The glow color comes from `--spotlight-color` (defaults to `--highlight`) and its strength from
`--spotlight-strength` (10%, 18% in dark mode; keep muted text at 4.5:1 if you raise it). The light follows mice
and pens only; keyboard focus inside the card lights the rim instead. Content that
must be clipped (images) should round itself — the card can't use `overflow: hidden`
without clipping its own rim light.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `string` | — | Any CSS color. Defaults to the theme's highlight token. |
| `size` | `number` | `420` | Diameter of the glow in px. |

Also accepts every `div` prop.

### SpotlightGroup

Tracks one pointer for every `<SpotlightCard>` inside, so the rim light spills across
neighboring cards (lay the cards out with your own grid classes).

Also accepts every `div` prop.



---

# Stacked Cards

> Featured projects as large sticky cards that stack while you scroll. Each card shrinks and dims as the next one covers it.

Category: Work · Registry item: `@portfolio-kit/stacked-cards` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/stacked-cards) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/stacked-cards.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/stacked-cards
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/stacked-cards.tsx` and the kit items it uses: `arrow-link`, `typography`, `use-composed-refs`, `use-reduced-motion`.

## Usage

```tsx
import {
  StackedCard,
  StackedCardContent,
  StackedCardDescription,
  StackedCardLink,
  StackedCardMedia,
  StackedCardMeta,
  StackedCardTags,
  StackedCardTitle,
  StackedCards,
} from "@/components/portfolio/stacked-cards"

<StackedCards>
  <StackedCard>
    <StackedCardMedia>
      <img src="/lumen.jpg" alt="" />
    </StackedCardMedia>
    <StackedCardContent>
      <StackedCardMeta>
        <span>Halcyon Labs</span>
        <span>2025</span>
      </StackedCardMeta>
      <StackedCardTitle>Lumen</StackedCardTitle>
      <StackedCardDescription>A design system for eleven products.</StackedCardDescription>
      <StackedCardTags tags={["Design system", "React"]} />
      <StackedCardLink href="/work/lumen">View case study</StackedCardLink>
    </StackedCardContent>
  </StackedCard>
</StackedCards>
```

## Examples

### Demo

Featured case studies as large sticky cards. Scroll, and each one shrinks and dims as the next slides over it.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  Section,
  SectionContent,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import {
  StackedCard,
  StackedCardContent,
  StackedCardDescription,
  StackedCardLink,
  StackedCardMedia,
  StackedCardMeta,
  StackedCardTags,
  StackedCardTitle,
  StackedCards,
} from "@/components/portfolio/stacked-cards"

const featured = [
  {
    slug: "lumen",
    title: "Lumen",
    client: "Halcyon Labs",
    year: 2025,
    summary: "A design system and component platform powering eleven products and 140 engineers.",
    tags: ["Design systems", "React", "Tokens"],
    art: "interface",
    hue: 250,
  },
  {
    slug: "tidewater",
    title: "Tidewater",
    client: "Tidewater Energy",
    year: 2025,
    summary: "Real-time grid monitoring for coastal wind farms — dense data, calm interface.",
    tags: ["Data viz", "Dashboard"],
    art: "interface",
    hue: 195,
  },
  {
    slug: "fieldnote",
    title: "Fieldnote",
    client: "Fieldnote Inc.",
    year: 2024,
    summary: "Identity and marketing site for a note-taking app built for researchers.",
    tags: ["Branding", "Next.js", "Motion"],
    art: "bauhaus",
    hue: 132,
  },
] as const

export default function StackedCardsDemo() {
  return (
    <Section className="pb-[50vh] md:pb-[50vh]">
      <SectionHeader>
        <SectionEyebrow index={1}>Featured</SectionEyebrow>
        <SectionTitle>Selected case studies</SectionTitle>
      </SectionHeader>
      <SectionContent>
        <StackedCards top="2rem">
          {featured.map((project, i) => (
            <StackedCard key={project.slug}>
              <StackedCardMedia>
                <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
              </StackedCardMedia>
              <StackedCardContent>
                <div className="flex flex-col gap-4">
                  <StackedCardMeta>
                    <span className="text-highlight-ink">{String(i + 1).padStart(2, "0")}</span>
                    <span>{project.client}</span>
                    <span>{project.year}</span>
                  </StackedCardMeta>
                  <StackedCardTitle>{project.title}</StackedCardTitle>
                  <StackedCardDescription>{project.summary}</StackedCardDescription>
                </div>
                <div className="flex flex-col gap-6">
                  <StackedCardTags tags={[...project.tags]} />
                  <StackedCardLink href={`#${project.slug}`}>
                    View case study<span className="sr-only">: {project.title}</span>
                  </StackedCardLink>
                </div>
              </StackedCardContent>
            </StackedCard>
          ))}
        </StackedCards>
      </SectionContent>
    </Section>
  )
}
```

### Compact

Shorter cards with a tight peek and a smaller shrink, for a homepage where the stack is one section among several.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Container } from "@/components/portfolio/section"
import {
  StackedCard,
  StackedCardContent,
  StackedCardDescription,
  StackedCardLink,
  StackedCardMedia,
  StackedCardMeta,
  StackedCardTitle,
  StackedCards,
} from "@/components/portfolio/stacked-cards"

const projects = [
  { slug: "orbit", title: "Orbit Analytics", role: "Front-end", summary: "Privacy-first product analytics with a query builder anyone can use.", art: "interface", hue: 20 },
  { slug: "kiln", title: "Kiln", role: "Design & build", summary: "A storefront for a small ceramics studio, shot and built in three weeks.", art: "landscape", hue: 330 },
  { slug: "paperplane", title: "Paperplane", role: "Maintainer", summary: "A tiny, typed animation library for React with 4k stars.", art: "rings", hue: 290 },
] as const

export default function StackedCardsCompact() {
  return (
    <Container size="sm" className="pt-8 pb-[60vh] md:pt-12">
      <StackedCards top="1.5rem" offset="0.75rem" scale={0.04}>
        {projects.map((project) => (
          <StackedCard key={project.slug} className="md:min-h-80">
            <StackedCardMedia>
              <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
            </StackedCardMedia>
            <StackedCardContent className="md:p-8 lg:p-8">
              <div className="flex flex-col gap-3">
                <StackedCardMeta>
                  <span>{project.role}</span>
                </StackedCardMeta>
                <StackedCardTitle className="md:text-4xl">{project.title}</StackedCardTitle>
                <StackedCardDescription className="md:text-base">{project.summary}</StackedCardDescription>
              </div>
              <StackedCardLink href={`#${project.slug}`}>
                Read more<span className="sr-only">: {project.title}</span>
              </StackedCardLink>
            </StackedCardContent>
          </StackedCard>
        ))}
      </StackedCards>
    </Container>
  )
}
```

### Full Bleed

A photographer’s series as full-bleed covers: the media fills each card and the text sits on a dark scrim, so the pictures lead.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Container } from "@/components/portfolio/section"
import {
  StackedCard,
  StackedCardContent,
  StackedCardDescription,
  StackedCardLink,
  StackedCardMedia,
  StackedCardMeta,
  StackedCardTitle,
  StackedCards,
} from "@/components/portfolio/stacked-cards"

const series = [
  { slug: "salt-flats", title: "Salt Flats", place: "Atacama", year: 2025, frames: 24, summary: "Three weeks of white ground and hard noon light, shot on medium format.", art: "landscape" },
  { slug: "night-ferries", title: "Night Ferries", place: "Lisbon", year: 2024, frames: 18, summary: "Commuters on the last crossings of the Tagus, lit only by the cabin.", art: "landscape" },
  { slug: "glasshouse", title: "Glasshouse", place: "Kew", year: 2023, frames: 31, summary: "A year of the same palm house, photographed on the first of every month.", art: "landscape" },
] as const

export default function StackedCardsFullBleed() {
  return (
    <Container className="pt-8 pb-[50vh] md:pt-12">
      <StackedCards top="1.5rem" offset="1rem">
        {series.map((item) => (
          // `dark` switches the card to the theme's dark palette, so text stays readable on any photo.
          <StackedCard key={item.slug} className="dark min-h-[28rem] md:min-h-[75vh] md:grid-cols-1">
            <StackedCardMedia className="absolute inset-0 aspect-auto max-md:border-b-0 md:border-l-0">
              <GenerativeArt seed={item.slug} variant={item.art} />
            </StackedCardMedia>
            <span aria-hidden className="pointer-events-none absolute inset-0 bg-gradient-to-t from-black/80 via-black/35 to-transparent" />
            <StackedCardContent className="relative justify-end md:justify-end md:gap-6">
              <div className="flex flex-col gap-3">
                <StackedCardMeta className="text-foreground/80">
                  <span>{item.place}</span>
                  <span>{item.year}</span>
                  <span>{item.frames} frames</span>
                </StackedCardMeta>
                <StackedCardTitle className="text-foreground">{item.title}</StackedCardTitle>
                <StackedCardDescription className="text-foreground/80">{item.summary}</StackedCardDescription>
              </div>
              <StackedCardLink href={`#${item.slug}`} className="text-foreground">
                View series<span className="sr-only">: {item.title}</span>
              </StackedCardLink>
            </StackedCardContent>
          </StackedCard>
        ))}
      </StackedCards>
    </Container>
  )
}
```

## API Reference

### StackedCards

The sticky stack (`<ul>`). Put `StackedCard`s inside, as direct children (a `.map()` is fine).
Progress is computed in a rAF-throttled scroll listener and written to `--stack-progress` on each
card (0 = in front, 1+ = covered by one or more cards), with no React state per scroll. Cards taller
than the viewport scroll fully into view before they stick, and a link that gets keyboard focus
under a later card is scrolled back into view. With reduced motion, and in print, the cards are a
plain list: no sticking, shrinking or dimming.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `top` | `string` | `"6rem"` | Distance from the top of the viewport where the first card sticks (clear your header). Any CSS length. |
| `offset` | `string` | `"1.5rem"` | Extra offset per card so the edges of earlier cards peek out above. Any CSS length. |
| `scale` | `number` | `0.06` | How much a fully covered card shrinks (0–1). `0` turns the shrink off. |

Also accepts every `ul` prop.

### StackedCard

One sticky card (`<li>`): content beside the media from `md` up, media on top on phones.
Put a `StackedCardMedia` and a `StackedCardContent` inside.

Also accepts every `li` prop.

### StackedCardMedia

Cover slot: an `<img>` (cropped to fill) or `<GenerativeArt />`. 16:10 on phones; on wider
screens it fills the right-hand column at the card's full height.

Also accepts every `div` prop.

### StackedCardContent

Text column. It spreads its children top to bottom from `md` up. Group the meta, title and
description in one `<div>` and the tags and link in another to pin them to the top and bottom.

Also accepts every `div` prop.

### StackedCardMeta

Eyebrow line (index, client, year). Pass `<span>`s; they're separated by short rules. Each rule
belongs to the item after it, and a wrapped line never starts or ends with one.

Also accepts every `div` prop.

### StackedCardTitle

Section-scale project name.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level. Match your page outline. |

Also accepts every `h3` prop.

### StackedCardDescription

One or two sentences on the brief and the outcome.

Also accepts every `p` prop.

### StackedCardTags

Tag chips.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tags` (required) | `string[]` | — | Short labels such as stack, discipline or deliverables. |
| `label` | `string` | `"Tags"` | Accessible name of the tag list. Translate it here. |

Also accepts every `ul` prop.

### StackedCardLink

"View case study" link. Stretches over the whole card so the card is one click target. Several
cards means several identical link texts, so add the project name for screen readers, e.g.
`View case study<span className="sr-only">: Lumen</span>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"default" \| "muted" \| "highlight"` | — | Text color: `default` foreground, `muted` for secondary links, `highlight` for the one call to action in a block. |
| `underline` | `"hover" \| "always" \| "none"` | — | `hover`: the underline draws in on hover and focus. `always`: underlined at rest (it retracts on hover), for links that must read as links without a pointer, such as an email address. `none`: only the arrow moves. |
| `arrow` | `"right" \| "up-right" \| "none"` | — | Arrow direction. Defaults to `up-right` (↗) for external links and `right` (→) otherwise. Both mirror in right-to-left text. |
| `external` | `boolean` | — | Open in a new tab with `rel="noopener noreferrer"`. Auto-detected from `href` (absolute `http(s)://` or protocol-relative URLs) when omitted. |
| `newTabLabel` | `string` | — | Screen-reader text added to links that open in a new tab. Translate it for non-English sites. |
| `asChild` | `boolean` | — | Render your router's link instead of `<a>` (e.g. Next.js `<Link>`): pass it as the only child and the arrow, underline and styles are merged onto it. |

Also accepts every `ArrowLink` prop.

## Used in templates

- [Studio](https://www.parthjadhav.com/products/portfolio-kit/templates/studio.md)



---

# Stats

> Headline numbers (years, projects, stars, awards) that count up as they scroll into view. Plain, divided or card layouts.

Category: About · Registry item: `@portfolio-kit/stats` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/stats) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/stats.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/stats
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/stats.tsx` and the kit items it uses: `number-ticker`, `typography`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  Stat,
  StatDescription,
  StatLabel,
  StatValue,
  StatsGrid,
} from "@/components/portfolio/stats"

<StatsGrid>
  <Stat>
    <StatValue value={9} suffix="+" />
    <StatLabel>Years of practice</StatLabel>
    <StatDescription>Across product, brand and front end.</StatDescription>
  </Stat>
  <Stat>
    <StatValue value={60} />
    <StatLabel>Projects shipped</StatLabel>
  </Stat>
</StatsGrid>
```

## Examples

### Demo

Four headline numbers that count up as they scroll into view, each with a label and a line of context.

```tsx
import { Stat, StatDescription, StatLabel, StatsGrid, StatValue } from "@/components/portfolio/stats"

export default function StatsDemo() {
  return (
    <StatsGrid className="mx-auto w-full max-w-5xl">
      <Stat>
        <StatValue value={9} suffix="+" />
        <StatLabel>Years of practice</StatLabel>
        <StatDescription>Across product, brand and front-end engineering.</StatDescription>
      </Stat>
      <Stat>
        <StatValue value={60} />
        <StatLabel>Projects shipped</StatLabel>
        <StatDescription>From two-week sprints to multi-year platforms.</StatDescription>
      </Stat>
      <Stat>
        <StatValue value={4.8} decimals={1} suffix="k" locale="en-US" />
        <StatLabel>GitHub stars</StatLabel>
        <StatDescription>On open-source tools used by thousands.</StatDescription>
      </Stat>
      <Stat>
        <StatValue value={12} />
        <StatLabel>Awards</StatLabel>
        <StatDescription>Including two site-of-the-day features.</StatDescription>
      </Stat>
    </StatsGrid>
  )
}
```

### Divided

Hairline rules between cells so the numbers read like a table. Counters mix with plain text values like “AA”.

```tsx
import { Stat, StatLabel, StatsGrid, StatValue } from "@/components/portfolio/stats"

export default function StatsDivided() {
  return (
    <StatsGrid variant="divided" columns={2} className="mx-auto w-full max-w-2xl">
      <Stat>
        <StatValue value={140} suffix="+" />
        <StatLabel>Engineers on Lumen</StatLabel>
      </Stat>
      <Stat>
        <StatValue value={11} />
        <StatLabel>Products, one system</StatLabel>
      </Stat>
      <Stat>
        <StatValue prefix="<">2s</StatValue>
        <StatLabel>Median page load</StatLabel>
      </Stat>
      <Stat>
        <StatValue>AA</StatValue>
        <StatLabel>WCAG level, every product</StatLabel>
      </Stat>
    </StatsGrid>
  )
}
```

### Cards

Each number on its own card. Fits a bento grid or sits next to a testimonial.

```tsx
import { Stat, StatDescription, StatLabel, StatsGrid, StatValue } from "@/components/portfolio/stats"

export default function StatsCards() {
  return (
    <StatsGrid variant="cards" columns={3} className="mx-auto w-full max-w-4xl grid-cols-1 sm:grid-cols-3">
      <Stat>
        <StatValue value={3.2} decimals={1} suffix="×" locale="en-US" />
        <StatLabel>Faster checkout</StatLabel>
        <StatDescription>After the Kiln storefront rebuild.</StatDescription>
      </Stat>
      <Stat>
        <StatValue value={40} />
        <StatLabel>Wind farms monitored</StatLabel>
        <StatDescription>On the Tidewater dashboard, in real time.</StatDescription>
      </Stat>
      <Stat>
        <StatValue value={400} suffix="k" />
        <StatLabel>Patients served</StatLabel>
        <StatDescription>By the Meridian portal every month.</StatDescription>
      </Stat>
    </StatsGrid>
  )
}
```

### In a Section

A “by the numbers” band under a section heading, using the divided layout: four columns on desktop, two on phones.

```tsx
import {
  Section,
  SectionContent,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import { Stat, StatLabel, StatsGrid, StatValue } from "@/components/portfolio/stats"

const stats = [
  { value: 9, suffix: "+", label: "Years of practice" },
  { value: 60, label: "Projects shipped" },
  { value: 24, label: "Happy clients" },
  { value: 12, label: "Awards" },
]

export default function StatsInASection() {
  return (
    <Section spacing="sm">
      <SectionHeader>
        <SectionEyebrow index={2}>By the numbers</SectionEyebrow>
        <SectionTitle>Nine years of careful, shipped work</SectionTitle>
      </SectionHeader>
      <SectionContent>
        <StatsGrid variant="divided">
          {stats.map((stat) => (
            <Stat key={stat.label}>
              <StatValue value={stat.value} suffix={stat.suffix} />
              <StatLabel>{stat.label}</StatLabel>
            </Stat>
          ))}
        </StatsGrid>
      </SectionContent>
    </Section>
  )
}
```

## API Reference

### StatsGrid

The list of stats. Every `Stat` inside follows its `variant`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "divided" \| "cards" \| null` | `"default"` | `default`: numbers over a hairline. `divided`: table-like cells with rules between them. `cards`: each stat on its own card. |
| `columns` | `2 \| 3 \| 4 \| null` | `4` | Columns from `md` up. Phones always show two. |

Also accepts every `ul` prop.

### Stat

One stat. Put a `StatValue`, a `StatLabel` and optionally a `StatDescription` inside. The value is always drawn first.

Also accepts every `li` prop.

### StatValue

The big number. Pass `value` to count up when it scrolls into view, or any text as children.
The final number is in the server HTML, in print and under reduced motion, and screen readers
only ever hear the final value. Phones show two stats per row, which fits about five
characters at this size: use `compact` (1.3M) for bigger numbers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `duration` | `number` | — | Animation length in ms. |
| `from` | `number` | — | Where the count starts. |
| `compact` | `boolean` | — | Compact notation: 4800 → "4.8K". |
| `locale` | `string` | — | BCP 47 locale for `Intl.NumberFormat`. Fixed to `en-US` by default so the server and the browser render the same text (the runtime default differs between them); pass your site's locale. |
| `delay` | `number` | — | Delay after entering the viewport, in ms. |
| `decimals` | `number` | — | Fraction digits shown (fixed, so the width never changes). |
| `formatOptions` | `Intl.NumberFormatOptions` | — | Extra `Intl.NumberFormat` options (currency, percent, units…). |
| `value` | `number` | — | A number counts up with `NumberTicker`. Otherwise pass `children` (e.g. "24/7"). |
| `prefix` | `React.ReactNode` | — | Shown before the value in a quieter color, e.g. "$" or "<". |
| `suffix` | `React.ReactNode` | — | Shown after the value in a quieter color, e.g. "+", "%" or "k". |

Also accepts every `p` prop.

### StatLabel

What the number counts, e.g. "Projects shipped".

Also accepts every `p` prop.

### StatDescription

A line of context under the label.

Also accepts every `p` prop.

## Used in templates

- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Sticker Board

> Playful stickers and polaroids scattered over a section that visitors can pick up, drag, drop and nudge with the arrow keys, with a spring settle and a reset.

Category: Effects · Registry item: `@portfolio-kit/sticker-board` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/sticker-board) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/sticker-board.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/sticker-board
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/sticker-board.tsx` and the kit items it uses: `use-composed-refs`, `use-reduced-motion`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import {
  Sticker,
  StickerBoard,
  StickerBoardReset,
  StickerPolaroid,
} from "@/components/portfolio/sticker-board"

<StickerBoard className="h-[480px]">
  <Sticker label="Polaroid: Lisbon, 2025" x={20} y={30} rotate={-8}>
    <StickerPolaroid caption="Lisbon, 2025">
      <img src="/lisbon.jpg" alt="" />
    </StickerPolaroid>
  </Sticker>
  <Sticker label="Sticker: Open to work" x={70} y={70} rotate={6}>
    <span>Open to work</span>
  </Sticker>
  <StickerBoardReset />
</StickerBoard>
```

## Examples

### Demo

An about section you can play with: pick up the photos and stickers, drag them around, or focus one and use the arrow keys.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  Sticker,
  StickerBoard,
  StickerBoardReset,
  StickerPolaroid,
} from "@/components/portfolio/sticker-board"
import { typography } from "@/lib/typography"

export default function StickerBoardDemo() {
  return (
    <StickerBoard className="h-dvh min-h-[480px] bg-muted/40">
      <div className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center gap-4 px-6 text-center">
        <p className={typography.eyebrow}>About</p>
        <h2 className={`${typography.title} max-w-xl`}>A designer who still keeps a scrapbook</h2>
      </div>

      <Sticker label="Polaroid: Lisbon, 2025" x={16} y={30} rotate={-8}>
        <StickerPolaroid caption="Lisbon, 2025">
          <GenerativeArt as="span" seed="lisbon" variant="landscape" />
        </StickerPolaroid>
      </Sticker>
      <Sticker label="Polaroid: the studio" x={84} y={28} rotate={6}>
        <StickerPolaroid caption="the studio">
          <GenerativeArt as="span" seed="studio" variant="portrait" />
        </StickerPolaroid>
      </Sticker>
      <Sticker label="Polaroid: first print run" x={78} y={76} rotate={-4}>
        <StickerPolaroid caption="first print run">
          <GenerativeArt as="span" seed="print" variant="rings" />
        </StickerPolaroid>
      </Sticker>
      <Sticker label="Sticker: Open to work" x={26} y={78} rotate={-10}>
        <span className="inline-flex items-center gap-2 rounded-pill bg-highlight px-4 py-2 font-mono text-sm font-medium tracking-wide whitespace-nowrap text-highlight-foreground uppercase shadow-card md:px-5 md:py-2.5 md:text-base">
          <span aria-hidden className="size-2 rounded-full bg-current" />
          Open to work
        </span>
      </Sticker>
      <Sticker label="Sticker: coffee-powered" x={50} y={16} rotate={4}>
        <span className="grid size-20 place-items-center rounded-full border bg-card text-center font-heading text-sm leading-tight text-card-foreground shadow-card md:size-28 md:text-lg">
          coffee
          <br />
          powered
        </span>
      </Sticker>

      <StickerBoardReset className="absolute right-4 bottom-4 z-[999]" />
    </StickerBoard>
  )
}
```

### Scattered

Leave out `x`/`y` and pass `index`: stickers scatter themselves in a fixed, repeatable pattern. Here, a card of things I like.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Sticker, StickerBoard, StickerBoardReset } from "@/components/portfolio/sticker-board"
import { typography } from "@/lib/typography"

const likes = ["Risograph", "Night walks", "Type specimens", "Film cameras", "Tiny tools", "Good coffee"]

export default function StickerBoardScattered() {
  return (
    <StickerBoard className="mx-auto h-96 max-w-3xl rounded-2xl border bg-card text-card-foreground shadow-card">
      <p className={`${typography.eyebrow} absolute top-5 left-5`}>Things I like</p>
      {likes.map((like, index) => (
        <Sticker key={like} index={index} label={`Sticker: ${like}`}>
          <span className="inline-flex items-center gap-2 rounded-pill border bg-background py-1.5 pr-3.5 pl-1.5 text-sm font-medium whitespace-nowrap shadow-card">
            <span className="size-6 overflow-hidden rounded-full">
              <GenerativeArt as="span" seed={like} variant="orb" grain={false} />
            </span>
            {like}
          </span>
        </Sticker>
      ))}
      <StickerBoardReset className="absolute right-4 bottom-4 z-[999]" />
    </StickerBoard>
  )
}
```

### Kind Words

Testimonials as notes pinned to a board, for a studio that wants its social proof to feel handmade rather than a carousel.

```tsx
import { cn } from "@/lib/utils"
import { Sticker, StickerBoard, StickerBoardReset } from "@/components/portfolio/sticker-board"
import { typography } from "@/lib/typography"

const notes = [
  { quote: "They turned a forty-page brief into one calm, obvious homepage.", author: "Mara Quint", company: "Fieldnote", x: 22, y: 30, rotate: -5 },
  { quote: "The only agency that asked to meet our support team first.", author: "Theo Lind", company: "Tidewater", x: 76, y: 26, rotate: 4, highlight: true },
  { quote: "Launched two weeks early. Nobody on our side believes it yet.", author: "Ines Arco", company: "Kiln Ceramics", x: 27, y: 74, rotate: 3 },
  { quote: "Our sign-ups doubled and the site finally sounds like us.", author: "Sam Okoro", company: "Orbit", x: 74, y: 74, rotate: -3 },
]

export default function StickerBoardKindWords() {
  return (
    <StickerBoard className="h-dvh min-h-[560px] bg-muted/40">
      <div className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center gap-3 px-6 text-center">
        <p className={typography.eyebrow}>Kind words</p>
        <h2 className={cn(typography.title, "max-w-md")}>Notes from the people we work with</h2>
      </div>

      {notes.map((note) => (
        <Sticker
          key={note.author}
          label={`Note from ${note.author}, ${note.company}: “${note.quote}”`}
          x={note.x}
          y={note.y}
          rotate={note.rotate}
        >
          {/* Spans only: a sticker is a <button>, which can't hold a <figure> or <blockquote>. */}
          <span
            className={cn(
              "flex w-40 flex-col gap-3 rounded-md border p-4 shadow-card sm:w-56 md:w-64 md:p-5",
              note.highlight ? "border-transparent bg-highlight text-highlight-foreground" : "bg-card text-card-foreground"
            )}
          >
            <span className="font-heading text-sm leading-snug text-pretty md:text-lg">“{note.quote}”</span>
            <span className="font-mono text-[0.6875rem] leading-tight tracking-wide uppercase md:text-xs">
              {note.author} · {note.company}
            </span>
          </span>
        </Sticker>
      ))}

      <StickerBoardReset className="absolute right-4 bottom-4 z-[999]" />
    </StickerBoard>
  )
}
```

## API Reference

### StickerBoard

The area stickers live in. Give it a height (`h-[520px]`, `min-h-[70vh]`…). Put `Sticker`s and
anything else (a headline, a `StickerBoardReset`) inside; stickers can't be dragged out of it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `instructions` | `string` | `"Drag to move, or use the arrow keys (hold Shift for bigger steps)."` | Instructions for screen-reader and keyboard users, announced with each sticker. |
| `hint` | `string` | — | Deprecated alias of `instructions`. |

Also accepts every `div` prop.

### Sticker

One draggable item. Put an image, `<GenerativeArt as="span" />`, an emoji or a small card inside, and size
it with `className`. Focusable: arrow keys move it by 8px (Shift: 40px). It is a `<button>`, so build its
content from spans and images, not `<div>`, `<p>` or `<figure>` (`StickerPolaroid` follows this).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | — | Accessible name, e.g. "Polaroid: Lisbon, 2025". Required, since stickers are often images. |
| `x` | `number` | — | Starting horizontal position of the sticker's center, in % of the board. Scattered by index when omitted. |
| `y` | `number` | — | Starting vertical position of the sticker's center, in % of the board. |
| `rotate` | `number` | — | Resting tilt in degrees. |
| `index` | `number` | `0` | Position in the board, used for the automatic scatter when `x`/`y` are omitted. |

Also accepts every `button` prop.

### StickerPolaroid

A bordered photo print with an optional caption, in the theme's card colors. Put an image or `<GenerativeArt as="span" />` inside.
It renders `<span>`s, not a `<figure>`: a `Sticker` is a `<button>`, which may only hold phrasing content, so
anything you put in a sticker should be spans too. The sticker's `label` names the photo.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `caption` | `React.ReactNode` | — | Handwritten-style line under the photo, e.g. a place and year. |

Also accepts every `span` prop.

### StickerBoardReset

Puts every sticker back where it started.

Also accepts every `button` prop.



---

# Sticky Layout

> Two-column page layout: a pinned intro with scrollspy navigation on the left and scrolling sections on the right.

Category: Layout · Registry item: `@portfolio-kit/sticky-layout` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/sticky-layout) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/sticky-layout.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/sticky-layout
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/sticky-layout.tsx` and the kit items it uses: `typography`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  StickyLayout,
  StickyLayoutAside,
  StickyLayoutMain,
  StickyLayoutNav,
  StickyLayoutSection,
  StickyLayoutSectionTitle,
} from "@/components/portfolio/sticky-layout"

<StickyLayout>
  <StickyLayoutAside>
    <h1>Noa Vale</h1>
    <StickyLayoutNav
      items={[
        { id: "about", label: "About" },
        { id: "work", label: "Work" },
      ]}
    />
  </StickyLayoutAside>
  <StickyLayoutMain>
    <StickyLayoutSection id="about">
      <StickyLayoutSectionTitle>About</StickyLayoutSectionTitle>
      <p>I design and build calm, fast interfaces.</p>
    </StickyLayoutSection>
    <StickyLayoutSection id="work">
      <StickyLayoutSectionTitle>Work</StickyLayoutSectionTitle>
    </StickyLayoutSection>
  </StickyLayoutMain>
</StickyLayout>
```

## Examples

### Demo

A one-page developer portfolio: the intro and scrollspy nav stay pinned on the left while sections scroll on the right.

```tsx
import { cn } from "@/lib/utils"
import { AvailabilityBadge } from "@/components/portfolio/availability-badge"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { SocialLink, SocialLinks } from "@/components/portfolio/social-links"
import {
  StickyLayout,
  StickyLayoutAside,
  StickyLayoutMain,
  StickyLayoutNav,
  StickyLayoutSection,
  StickyLayoutSectionTitle,
} from "@/components/portfolio/sticky-layout"
import { TagList } from "@/components/portfolio/tag-list"
import { typography } from "@/lib/typography"

const sections = [
  { id: "about", label: "About" },
  { id: "experience", label: "Experience" },
  { id: "projects", label: "Projects" },
]

const socials = ["https://github.com/example", "https://www.linkedin.com/in/example", "https://read.cv/example", "mailto:hello@example.com"]

const experience = [
  {
    company: "Halcyon Labs",
    role: "Staff Design Engineer",
    start: "2022",
    end: "Present",
    summary: "Lead the Lumen design system; partner with 11 product teams on UI architecture, accessibility and motion.",
    tags: ["React", "TypeScript", "Design tokens"],
  },
  {
    company: "Paperplane Studio",
    role: "Senior Product Designer",
    start: "2019",
    end: "2022",
    summary: "Shipped products for fintech and climate clients from first sketch to production code.",
    tags: ["Product design", "Prototyping"],
  },
  {
    company: "Meridian Health",
    role: "Front-end Engineer",
    start: "2016",
    end: "2019",
    summary: "Built the patient portal used by 400k people; led the migration to a component library.",
    tags: ["Vue", "Accessibility"],
  },
]

const projects = [
  { slug: "lumen", title: "Lumen", year: 2025, summary: "A design system powering eleven products and 140 engineers.", art: "interface" },
  { slug: "tidewater", title: "Tidewater", year: 2025, summary: "Real-time grid monitoring for coastal wind farms.", art: "interface" },
  { slug: "paperplane", title: "Paperplane", year: 2023, summary: "A tiny, typed animation library for React.", art: "rings" },
] as const

export default function StickyLayoutDemo() {
  return (
    <StickyLayout>
      <StickyLayoutAside>
        <div className="flex flex-col gap-10 lg:gap-14">
          <div className="flex flex-col gap-4">
            <h1 className="font-heading text-4xl leading-none sm:text-5xl">Noa Vale</h1>
            <p className="font-heading text-lg md:text-xl">Design Engineer at Halcyon Labs</p>
            <p className={cn(typography.body, "max-w-xs")}>
              I design and build calm, fast interfaces for ambitious product teams.
            </p>
          </div>
          <StickyLayoutNav items={sections} />
        </div>
        <div className="flex flex-col items-start gap-5">
          <AvailabilityBadge variant="plain" detail="from Nov" />
          <SocialLinks className="-ml-2">
            {socials.map((href) => (
              <SocialLink key={href} href={href} />
            ))}
          </SocialLinks>
        </div>
      </StickyLayoutAside>

      <StickyLayoutMain>
        <StickyLayoutSection id="about">
          <StickyLayoutSectionTitle>About</StickyLayoutSectionTitle>
          <div className="flex flex-col gap-4">
            <p className={typography.lead}>
              I&apos;m a design engineer working at the seam between product design and front-end engineering. For the
              last nine years I&apos;ve helped startups and studios turn rough ideas into interfaces that feel inevitable.
            </p>
            <p className={typography.lead}>
              Today I lead the design system at Halcyon Labs. Outside of work I shoot film, run along the river and tinker
              with generative art.
            </p>
          </div>
        </StickyLayoutSection>

        <StickyLayoutSection id="experience">
          <StickyLayoutSectionTitle>Experience</StickyLayoutSectionTitle>
          <ol role="list" className="flex flex-col gap-3">
            {experience.map((job) => (
              <li
                key={job.company}
                className="-mx-4 grid gap-2 rounded-xl p-4 transition-colors duration-300 hover:bg-muted/50 sm:grid-cols-[8rem_1fr] sm:gap-6"
              >
                <p className={cn(typography.meta, "pt-1")}>
                  <time dateTime={job.start}>{job.start}</time> — {job.end}
                </p>
                <div className="flex flex-col gap-2">
                  <h3 className={typography.heading}>
                    {job.role} · <span className="text-muted-foreground">{job.company}</span>
                  </h3>
                  <p className={typography.body}>{job.summary}</p>
                  <TagList tags={job.tags} aria-label="Skills" className="mt-1" />
                </div>
              </li>
            ))}
          </ol>
        </StickyLayoutSection>

        <StickyLayoutSection id="projects">
          <StickyLayoutSectionTitle>Projects</StickyLayoutSectionTitle>
          <ul role="list" className="flex flex-col gap-3">
            {projects.map((project) => (
              <li
                key={project.slug}
                className="-mx-4 grid grid-cols-[6rem_1fr] gap-4 rounded-xl p-4 transition-colors duration-300 hover:bg-muted/50 sm:grid-cols-[8rem_1fr] sm:gap-6"
              >
                <div className="aspect-[4/3] overflow-hidden rounded-lg border">
                  <GenerativeArt seed={project.slug} variant={project.art} />
                </div>
                <div className="flex flex-col gap-1.5">
                  <h3 className={typography.heading}>{project.title}</h3>
                  <p className={cn(typography.body, "line-clamp-2")}>{project.summary}</p>
                  <p className={typography.meta}>{project.year}</p>
                </div>
              </li>
            ))}
          </ul>
        </StickyLayoutSection>
      </StickyLayoutMain>
    </StickyLayout>
  )
}
```

### Numbered with Footer

A narrower aside with an indexed nav, and a footer under the main column that the pinned intro stays beside.

```tsx
import { cn } from "@/lib/utils"
import { ArrowLink } from "@/components/portfolio/arrow-link"
import { PostList, PostListItem } from "@/components/portfolio/post-list"
import {
  StickyLayout,
  StickyLayoutAside,
  StickyLayoutFooter,
  StickyLayoutMain,
  StickyLayoutNav,
  StickyLayoutSection,
  StickyLayoutSectionTitle,
} from "@/components/portfolio/sticky-layout"
import { TalkItem, TalkList } from "@/components/portfolio/talk-list"
import { typography } from "@/lib/typography"

const sections = [
  { id: "now", label: "Now" },
  { id: "writing", label: "Writing" },
  { id: "talks", label: "Talks" },
]

const posts = [
  { slug: "motion", title: "Designing motion that respects attention", date: "2025-09-02", readingTime: "7 min" },
  { slug: "tokens", title: "Tokens are an API: versioning a design system", date: "2025-06-18", readingTime: "11 min" },
  { slug: "navigation", title: "The case for boring navigation", date: "2025-03-04", readingTime: "5 min" },
  { slug: "oklch", title: "Notes on building with oklch()", date: "2024-11-21", readingTime: "9 min" },
]

const talks = [
  { slug: "attention", title: "Motion that respects attention", event: "Interface Days", location: "Porto", date: "2025-10-09" },
  { slug: "tokens-talk", title: "Tokens are an API", event: "Systems Summit", location: "Online", date: "2025-04-17" },
  { slug: "boring", title: "In praise of boring navigation", event: "Frontend Meetup", location: "Lisbon", date: "2024-12-05" },
]

export default function StickyLayoutNumbered() {
  return (
    <StickyLayout ratio="narrow">
      <StickyLayoutAside>
        <div className="flex flex-col gap-10 lg:gap-14">
          <div className="flex flex-col gap-3">
            <h1 className="font-heading text-4xl leading-none">Noa Vale</h1>
            <p className={cn(typography.body, "max-w-xs")}>Design engineer writing about motion, systems and the web.</p>
          </div>
          <StickyLayoutNav items={sections} numbered />
        </div>
        <ArrowLink href="mailto:hello@example.com" className="self-start text-sm">
          hello@example.com
        </ArrowLink>
      </StickyLayoutAside>

      <StickyLayoutMain>
        <StickyLayoutSection id="now">
          <StickyLayoutSectionTitle>Now</StickyLayoutSectionTitle>
          <p className={cn(typography.lead, "max-w-xl")}>
            Leading the design system at Halcyon Labs, writing a short book on interface motion, and learning to develop
            colour film at home — slowly.
          </p>
        </StickyLayoutSection>

        <StickyLayoutSection id="writing">
          <StickyLayoutSectionTitle>Writing</StickyLayoutSectionTitle>
          <PostList>
            {posts.map((post) => (
              <PostListItem
                key={post.slug}
                href={`#${post.slug}`}
                heading={post.title}
                date={post.date}
                readingTime={post.readingTime}
              />
            ))}
          </PostList>
        </StickyLayoutSection>

        <StickyLayoutSection id="talks">
          <StickyLayoutSectionTitle>Talks</StickyLayoutSectionTitle>
          <TalkList>
            {talks.map(({ slug, title, ...talk }) => (
              <TalkItem key={slug} heading={title} {...talk} links={{ slides: `#${slug}` }} />
            ))}
          </TalkList>
        </StickyLayoutSection>
      </StickyLayoutMain>

      <StickyLayoutFooter>
        <p className="max-w-md font-heading text-2xl leading-tight text-balance">Have a project in mind? Say hello.</p>
        <p className={typography.meta}>© 2025 Noa Vale</p>
      </StickyLayoutFooter>
    </StickyLayout>
  )
}
```

## API Reference

### StickyLayout

The page grid. Place `StickyLayoutAside`, `StickyLayoutMain` and optionally
`StickyLayoutFooter` as direct children, in that order: it is also the reading order.
Below `lg` everything stacks in one column.

Under a fixed or sticky site header, set `--sticky-layout-top` to the header's height
(e.g. `className="[--sticky-layout-top:4rem]"`, default `0px`): the aside pins below it,
the small-screen section titles stick below it and in-page links land below it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "lg" \| null` | `"default"` | Max width of the two-column grid: `default` (72rem) or `lg` (80rem). |
| `ratio` | `"balanced" \| "default" \| "narrow" \| null` | `"default"` | Column split from `lg` up: `balanced` (1:1), `default` (5:7) or `narrow` (4:8, a slimmer aside). |

Also accepts every `div` prop.

### StickyLayoutAside

The pinned column (a `<header>`): name, intro, nav and links. Top and bottom groups are
pushed apart on large screens. When its contents are taller than the window (a short
laptop screen, a long intro), the column scrolls on its own, so nothing in it is out of reach.

Also accepts every `header` prop.

### StickyLayoutMain

The scrolling column (a `<main>`) that holds the `StickyLayoutSection`s.

Also accepts every `main` prop.

### StickyLayoutFooter

Footer in the main column, under `StickyLayoutMain` (place it as a direct child of
`StickyLayout`). The aside automatically spans it, so it stays pinned to the end.

Also accepts every `footer` prop.

### StickyLayoutSection

A scroll-spied section. Give it the `id` you pass to `StickyLayoutNav`. It is labelled by
its `StickyLayoutSectionTitle` automatically (pass `aria-labelledby` to override), and
receives keyboard focus when its nav link is followed.

Also accepts every `section` prop.

### StickyLayoutSectionTitle

Section label. Pinned to the top of the viewport on small screens (where the nav is
hidden) and visually hidden on large screens, where the nav takes over. It stays in the
page outline at every size, and prints as a plain label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"h2" \| "h3"` | `"h2"` | Heading level. |

Also accepts every `h2` prop.

### StickyLayoutNav

Scrollspy navigation for the aside, shown from `lg` up (hidden in print). The link of the
section crossing `offset` gets `aria-current="location"` and an extended line. Following a
link scrolls to the section (smoothly, or instantly with reduced motion), updates the
`#hash` and moves keyboard focus to the section; the clicked link stays current until the
visitor scrolls again. Name the landmark in your language with `aria-label`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `NavItem[]` | — | One entry per section, in page order. |
| `offset` | `number` | `0.35` | Horizontal line across the viewport, as a fraction from the top, that decides which section is active. `0.35` means "the section crossing 35% of the viewport". At the very bottom of the page the last section is active, at the very top the first. |
| `numbered` | `boolean` | `false` | Show a zero-padded index (01, 02…) before each label. |
| `onActiveChange` | `(id: string) => void` | — | Called with the id of the section that becomes active. |

Also accepts every `nav` prop.

### type NavItem

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | — | Id of the `StickyLayoutSection` to link to. |
| `label` (required) | `React.ReactNode` | — | Link text. |

## Used in templates

- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)



---

# Table Of Contents

> Scrollspy navigation for case studies and articles, as a rail with a moving marker or a plain list. Clicking scrolls to the heading and updates the URL hash.

Category: Navigation · Registry item: `@portfolio-kit/table-of-contents` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/table-of-contents) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/table-of-contents.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/table-of-contents
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/table-of-contents.tsx` and the kit items it uses: `use-reduced-motion`.

## Usage

```tsx
import { TableOfContents, TableOfContentsItem } from "@/components/portfolio/table-of-contents"
```

## Examples

### Demo

A sticky rail beside a case study. The marker follows the section being read, and clicking a link scrolls to it.

```tsx
import { TableOfContents, type TableOfContentsEntry } from "@/components/portfolio/table-of-contents"
import { typography } from "@/lib/typography"

const sections: (TableOfContentsEntry & { label: string; body: string[] })[] = [
  {
    id: "overview",
    label: "Overview",
    body: [
      "Lumen started as a question: why did eleven products built by one company feel like eleven companies? The answer was a design system and component platform that now powers all of them.",
      "The brief was deliberately small: fewer decisions per screen, and one obvious place to make each of them. Everything else in this case study follows from that.",
    ],
  },
  {
    id: "research",
    label: "Research",
    body: [
      "We spent the first weeks listening. Every team had solved buttons, forms and empty states in slightly different ways, and every difference cost time in review.",
      "Support tickets told the same story from the other side — customers noticed the inconsistencies long before we had a name for them.",
    ],
  },
  {
    id: "interviews",
    label: "Stakeholder interviews",
    level: 3,
    body: [
      "Twenty-two conversations across design, engineering and support surfaced the same pain: nobody knew which version of a component was the right one.",
      "Engineers wanted fewer props, designers wanted fewer variants, and product managers wanted both teams to stop waiting on each other.",
    ],
  },
  {
    id: "audit",
    label: "Component audit",
    level: 3,
    body: [
      "We screenshotted every button in production. There were forty-one. Seeing them on one wall did more for buy-in than any slide deck.",
      "The audit became the backlog. Each duplicate was either merged, promoted into the system, or deleted outright.",
    ],
  },
  {
    id: "system",
    label: "Designing the system",
    body: [
      "Tokens came first — color, spacing and type as a versioned API with owners and a changelog. Components followed only once three teams had asked for the same thing.",
      "Every token and component shipped with a changelog entry, a migration note and an owner, so teams could upgrade on their own schedule.",
    ],
  },
  {
    id: "outcomes",
    label: "Outcomes",
    body: [
      "New screens now take days instead of weeks, and design reviews are about the product again rather than the padding.",
      "Eleven products now ship from one foundation, and the system team spends its time on new problems instead of old buttons.",
    ],
  },
]

export default function TableOfContentsDemo() {
  return (
    <div className="mx-auto grid max-w-5xl gap-10 px-5 py-14 sm:px-6 md:grid-cols-[12rem_minmax(0,1fr)] md:gap-16 md:px-8">
      <aside className="md:sticky md:top-10 md:self-start">
        <TableOfContents items={sections} offset={64} />
      </aside>
      <article className="flex max-w-2xl flex-col gap-10 pb-[50vh]">
        <header className="flex flex-col gap-4">
          <p className={typography.meta}>2025 / Halcyon Labs / Design lead</p>
          <h1 className={typography.title}>Lumen</h1>
        </header>
        {sections.map((section) => {
          const Heading = section.level === 3 ? "h3" : "h2"
          return (
            <section key={section.id} className="flex flex-col gap-4">
              <Heading
                id={section.id}
                className={
                  section.level === 3
                    ? "scroll-mt-10 font-heading text-lg leading-snug outline-none md:text-xl"
                    : "scroll-mt-10 font-heading text-2xl leading-tight outline-none md:text-3xl"
                }
              >
                {section.label}
              </Heading>
              {section.body.map((text) => (
                <p key={text} className={typography.body}>
                  {text}
                </p>
              ))}
            </section>
          )
        })}
      </article>
    </div>
  )
}
```

### Numbered List

The quieter `list` variant, composed from `TableOfContentsItem`s so you can add your own chapter numbers.

```tsx
import { TableOfContents, TableOfContentsItem } from "@/components/portfolio/table-of-contents"
import { typography } from "@/lib/typography"

const chapters = [
  {
    id: "context",
    title: "Context",
    body: [
      "Tidewater operators watched forty turbines across six browser tabs. Alarms arrived by email, minutes after the fact, and nobody trusted the numbers on screen.",
      "The operators weren't the problem. The tools were built for engineers debugging turbines, not for people watching forty of them at once.",
    ],
  },
  {
    id: "approach",
    title: "Approach",
    body: [
      "We shadowed three control-room shifts, then rebuilt the dashboard around a single question: what needs a human right now? Everything else became quiet by default.",
      "Every alarm was sorted into act now, act today or just know — and only the first group was allowed to make noise.",
    ],
  },
  {
    id: "interface",
    title: "Interface",
    body: [
      "One map, one alarm queue, one timeline. Color is reserved for things that need attention, so a calm screen really means a calm grid.",
      "Density stayed high, but hierarchy did the work: numbers you glance at are large, numbers you investigate are one click away.",
    ],
  },
  {
    id: "results",
    title: "Results",
    body: [
      "Median time to acknowledge an alarm fell from nine minutes to under one, and the six tabs became one screen operators leave open all day.",
      "Night shifts went from reactive to routine, and the team retired two legacy tools within a quarter of launch.",
    ],
  },
]

export default function TableOfContentsList() {
  return (
    <div className="mx-auto grid max-w-5xl gap-10 px-5 py-14 sm:px-6 md:grid-cols-[minmax(0,1fr)_12rem] md:gap-16 md:px-8">
      {/* First in the DOM, like it is on phones; moved to the right column from md up. */}
      <aside className="md:sticky md:top-10 md:order-last md:self-start">
        <TableOfContents variant="list" heading="Chapters" offset={64}>
          {chapters.map((chapter, i) => (
            <TableOfContentsItem key={chapter.id} id={chapter.id}>
              <span aria-hidden className="mr-2 font-mono text-xs text-muted-foreground tabular-nums">{String(i + 1).padStart(2, "0")}</span>
              {chapter.title}
            </TableOfContentsItem>
          ))}
        </TableOfContents>
      </aside>
      <article className="flex max-w-2xl flex-col gap-12 pb-[50vh]">
        <header className="flex flex-col gap-4">
          <p className={typography.eyebrow}>Case study</p>
          <h1 className={typography.title}>Tidewater</h1>
        </header>
        {chapters.map((chapter, i) => (
          <section key={chapter.id} className="flex flex-col gap-4">
            <p className={typography.meta}>{String(i + 1).padStart(2, "0")}</p>
            <h2 id={chapter.id} className="scroll-mt-10 font-heading text-2xl leading-tight outline-none md:text-3xl">
              {chapter.title}
            </h2>
            {chapter.body.map((text) => (
              <p key={text} className={typography.body}>
                {text}
              </p>
            ))}
          </section>
        ))}
      </article>
    </div>
  )
}
```

## API Reference

### TableOfContents

In-page navigation (a `<nav>` landmark) that highlights the heading being read with
`aria-current="location"`. Clicking an entry scrolls to the heading (smoothly, or instantly
with reduced motion), pushes the `#hash` and moves keyboard focus to the heading, so
keyboard and screen-reader users continue reading from there. The clicked entry stays
active until the visitor scrolls again.

Give your headings `scroll-mt-*` so they clear any sticky header; a heading counts as
reached at `offset` or at its scroll margin, whichever is lower on screen. Long labels wrap.
On narrow screens, stack it above the content (first in the DOM, so reading order matches)
or hide it; the marker is hidden in print.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"rail" \| "list"` | `"rail"` | `rail`: a vertical line with a marker that glides to the active heading. `list`: a quiet list with growing dashes. |
| `items` | `TocItem[]` | — | Convenience: render one link per heading. Or compose `TableOfContentsItem`s as children. |
| `heading` | `React.ReactNode` | `"On this page"` | Label shown above the links; it also names the navigation landmark. Pass `null` to hide it (then set `aria-label`). |
| `offset` | `number` | `96` | Distance (px) from the viewport top at which a heading becomes active. Match it to your sticky header height. |

Also accepts every `nav` prop.

### TableOfContentsItem

One entry. Compose these as children of `TableOfContents` to add numbers or icons.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | — | Id of the heading this item links to (it becomes the `href`). |
| `level` | `2 \| 3` | `2` | `3` indents the entry and sets it slightly smaller. |

Also accepts every `a` prop.

### type TocItem

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | — | Id of the heading to link to. |
| `label` (required) | `React.ReactNode` | — | Link text, usually the heading text, shortened if needed. |
| `level` | `2 \| 3` | — | `3` indents the entry under the previous level-2 heading. |

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)



---

# Tag List

> Pill tags for skills, stacks and topics — outline, soft or solid, with optional links, leading dots or icons and counts.

Category: Utilities · Registry item: `@portfolio-kit/tag-list` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/tag-list) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/tag-list.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/tag-list
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/tag-list.tsx`.

npm dependencies: `class-variance-authority`, `radix-ui`.

## Usage

```tsx
import { Tag, TagList } from "@/components/portfolio/tag-list"

<TagList aria-label="Toolkit">
  <Tag>Figma</Tag>
  <Tag>TypeScript</Tag>
  <Tag href="/tags/react">React</Tag>
</TagList>
```

## Examples

### Demo

A labelled list of skills or stack items — pass strings for the simple case and it renders a proper `<ul>`.

```tsx
import { TagList } from "@/components/portfolio/tag-list"
import { typography } from "@/lib/typography"

const skills = ["Design systems", "React", "TypeScript", "Motion", "Accessibility", "Prototyping", "Figma"]

export default function TagListDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <p className={typography.eyebrow}>Toolkit</p>
      <TagList aria-label="Toolkit" size="md" tags={skills} />
    </div>
  )
}
```

### Variants

Outline for quiet metadata, soft for grouped skills, solid for the one thing you want noticed. Dots and icons add a leading mark.

```tsx
import { Code2, Frame, PenTool, Sparkles } from "lucide-react"

import { Tag, TagList } from "@/components/portfolio/tag-list"
import { typography } from "@/lib/typography"

export default function TagListVariants() {
  return (
    <div className="flex w-full max-w-md flex-col gap-6">
      <div className="flex flex-col gap-2.5">
        <p className={typography.meta}>outline</p>
        <TagList aria-label="Outline tags" tags={["Design systems", "React", "Tokens"]} />
      </div>
      <div className="flex flex-col gap-2.5">
        <p className={typography.meta}>soft · icons</p>
        <TagList aria-label="Tools" variant="soft" size="md">
          <Tag icon={<Frame aria-hidden />}>Figma</Tag>
          <Tag icon={<Code2 aria-hidden />}>React</Tag>
          <Tag icon={<PenTool aria-hidden />}>Illustration</Tag>
          <Tag icon={<Sparkles aria-hidden />}>Motion</Tag>
        </TagList>
      </div>
      <div className="flex flex-col gap-2.5">
        <p className={typography.meta}>solid · dots</p>
        <TagList aria-label="Status">
          <Tag dot variant="solid">
            Featured
          </Tag>
          <Tag dot>Now booking Q1</Tag>
          <Tag dot variant="soft">
            Open source
          </Tag>
        </TagList>
      </div>
    </div>
  )
}
```

### Linked Topics

Give tags an `href` and a `count` for a blog's topic index — each one becomes a real link with a hover state, and `countLabel` makes the count read as "11 posts".

```tsx
import { TagList } from "@/components/portfolio/tag-list"
import { typography } from "@/lib/typography"

const topics = [
  { label: "Design systems", count: 11 },
  { label: "Motion", count: 6 },
  { label: "CSS", count: 9 },
  { label: "Accessibility", count: 4 },
]

export default function TagListTopics() {
  return (
    <nav aria-labelledby="topics-label" className="flex w-full max-w-sm flex-col gap-4">
      <p id="topics-label" className={typography.eyebrow}>
        Browse by topic
      </p>
      <TagList
        aria-label="Topics"
        size="md"
        tags={topics.map((topic) => ({
          label: topic.label,
          count: topic.count,
          countLabel: (n: number) => (n === 1 ? "post" : "posts"),
          href: `#topic-${topic.label.toLowerCase().replace(/\s+/g, "-")}`,
        }))}
      />
    </nav>
  )
}
```

### Truncated

`max` keeps busy rows tidy: extra tags collapse into a “+N” chip whose tooltip lists the rest.

```tsx
import { TagList } from "@/components/portfolio/tag-list"

const roles = [
  {
    role: "Staff Design Engineer",
    company: "Halcyon Labs",
    period: "2022 — Now",
    tags: ["Design systems", "React", "Tokens", "Motion", "Docs"],
  },
  {
    role: "Senior Product Designer",
    company: "Tidewater Energy",
    period: "2019 — 2022",
    tags: ["Data viz", "Dashboards", "Prototyping", "Research"],
  },
  {
    role: "Front-end Developer",
    company: "Studio Meridian",
    period: "2016 — 2019",
    tags: ["CSS", "WebGL"],
  },
]

export default function TagListTruncated() {
  return (
    <ul role="list" className="mx-auto flex max-w-3xl flex-col divide-y border-y">
      {roles.map((job) => (
        <li key={job.company} className="flex flex-col gap-3 py-5 sm:flex-row sm:items-center sm:justify-between sm:gap-8">
          <div className="flex min-w-0 flex-col gap-0.5">
            <p className="font-heading text-lg leading-snug">{job.role}</p>
            <p className="text-sm text-muted-foreground">
              {job.company} <span className="font-mono text-xs tabular-nums">· {job.period}</span>
            </p>
          </div>
          <TagList aria-label={`${job.company} skills`} tags={job.tags} max={3} className="sm:max-w-sm sm:justify-end" />
        </li>
      ))}
    </ul>
  )
}
```

## API Reference

### Tag

A single tag. Renders a `<span>`, or an `<a>` when `href` is set. Inside a `TagList` it inherits
the list's `variant`/`size` and is wrapped in an `<li>` for you.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | Renders an `<a>` with a hover state. |
| `variant` | `"outline" \| "soft" \| "solid"` | `"outline"` | `outline`: bordered, the quiet default. `soft`: muted fill, for many tags at once. `solid`: inverted, for the one tag that matters. Inherits from `TagList`. |
| `size` | `"sm" \| "md"` | `"sm"` | `sm` for dense rows and cards, `md` for standalone topic lists. Inherits from `TagList`. |
| `children` | `React.ReactNode` | — | The tag's label. |
| `dot` | `boolean` | — | Leading status dot in the highlight color. |
| `icon` | `React.ReactNode` | — | Leading icon (e.g. a lucide icon). |
| `count` | `number` | — | Trailing count, e.g. the number of posts with this tag. Screen readers hear it after a pause ("React, 12"). |
| `countLabel` | `string \| ((count: number) => string)` | — | Screen-reader words after the count, e.g. `"posts"` reads "React, 12 posts". A function gets the count, for plurals: `(n) => (n === 1 ? "post" : "posts")`. |
| `newTabLabel` | `string` | — | Screen-reader text for a tag link that opens in a new tab (absolute URLs do). Inherits from `TagList`. |
| `asChild` | `boolean` | — | Render your router's link instead of `<a>`. |

Also accepts every `a` prop.

### TagList

A `<ul>` of tags. Pass `tags` for the data-driven shortcut or compose `<Tag>` children; `variant`
and `size` set here apply to every tag inside. Labelled "Tags" unless you pass `aria-label` (translate it there).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"outline" \| "soft" \| "solid"` | `"outline"` | Style for every tag inside: `outline`, `soft` or `solid` (see `Tag`). |
| `size` | `"sm" \| "md"` | `"sm"` | Size for every tag inside: `sm` or `md`. |
| `tags` | `TagItem[]` | — | Shortcut for simple lists: strings or tag props with a `label`. |
| `max` | `number` | — | Show at most this many tags, followed by a "+N" tag (its tooltip lists the rest). Applies to `tags` only. |
| `moreLabel` | `string` | `"{count} more"` | What screen readers hear for the "+N" tag, before the hidden names; `{count}` is replaced. Translate it here. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text for tag links that open in a new tab. Translate it for non-English sites. |

Also accepts every `ul` prop.

### type TagItem

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `React.ReactNode` | — |  |
| `key` | `string` | — |  |
| `href` | `string` | — | Renders an `<a>` with a hover state. |
| `variant` | `"soft" \| "outline" \| "solid"` | — |  |
| `size` | `"sm" \| "md"` | — |  |
| `asChild` | `boolean` | — | Render your router's link instead of `<a>`. |
| `icon` | `React.ReactNode` | — | Leading icon (e.g. a lucide icon). |
| `dot` | `boolean` | — | Leading status dot in the highlight color. |
| `count` | `number` | — | Trailing count, e.g. the number of posts with this tag. Screen readers hear it after a pause ("React, 12"). |
| `countLabel` | `string \| ((count: number) => string)` | — | Screen-reader words after the count, e.g. `"posts"` reads "React, 12 posts". A function gets the count, for plurals: `(n) => (n === 1 ? "post" : "posts")`. |
| `newTabLabel` | `string` | — | Screen-reader text for a tag link that opens in a new tab (absolute URLs do). Inherits from `TagList`. |

## Used in templates

- [Article](https://www.parthjadhav.com/products/portfolio-kit/templates/article.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Talk List

> Talks, workshops and podcast appearances with event, location, date and links to slides or recordings. Future dates get an “Upcoming” badge.

Category: Content · Registry item: `@portfolio-kit/talk-list` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/talk-list) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/talk-list.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/talk-list
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/talk-list.tsx` and the kit items it uses: `arrow-link`, `format`, `typography`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import { TalkItem, TalkList } from "@/components/portfolio/talk-list"

<TalkList now="2025-09-01">
  <TalkItem
    heading="Tokens are an API"
    event="CSS Day Lisbon"
    location="Lisbon"
    date="2025-06-12"
    links={{ slides: "https://example.com/slides", video: "https://example.com/video" }}
  />
  <TalkItem heading="Building a token pipeline" event="Systems Summit" date="2025-11-06" kind="workshop" />
</TalkList>
```

## Examples

### Demo

Talks, workshops and podcasts with event, place and links to slides or recordings. Future dates get an “Upcoming” badge.

```tsx
import { TalkItem, TalkList } from "@/components/portfolio/talk-list"

export default function TalkListDemo() {
  return (
    // `now` is pinned so the demo always shows one upcoming talk. Without it, badges follow the
    // visitor's date and appear after hydration (pass your build date to server-render them).
    <TalkList now="2026-03-02" className="mx-auto max-w-3xl">
      <TalkItem
        heading="Motion with intent: animation as interface"
        event="Frontier Conf"
        location="Amsterdam"
        date="2026-05-21"
        href="https://example.com/talks/motion-with-intent"
        links={{ event: "https://example.com/frontier-conf" }}
      />
      <TalkItem
        heading="Building a token pipeline from scratch"
        event="Systems Summit"
        location="Remote"
        date="2025-11-06"
        kind="workshop"
        links={{ slides: "#slides-token-pipeline", recording: "#recording-token-pipeline" }}
      />
      <TalkItem
        heading="Tokens are an API"
        event="CSS Day Lisbon"
        location="Lisbon"
        date="2025-06-12"
        links={{ slides: "#slides-tokens", video: "#video-tokens" }}
      />
      <TalkItem
        heading="Design engineers and the space between"
        event="The Handoff Podcast"
        location="Episode 42"
        date="2025-03-27"
        kind="podcast"
        links={{ recording: "#podcast-42" }}
      />
    </TalkList>
  )
}
```

### Grouped by Year

For a long speaking history: talks grouped under a sticky year. Tune the pin offset with `--talk-list-sticky-top`.

```tsx
import type * as React from "react"

import { TalkItem, TalkList } from "@/components/portfolio/talk-list"

const talks: React.ComponentProps<typeof TalkItem>[] = [
  { heading: "Motion with intent", event: "Frontier Conf", location: "Amsterdam", date: "2026-05-21" },
  { heading: "Tokens are an API", event: "CSS Day Lisbon", location: "Lisbon", date: "2025-06-12", links: { slides: "#slides", video: "#video" } },
  { heading: "Design engineers and the space between", event: "The Handoff Podcast", location: "Episode 42", date: "2025-03-27", kind: "podcast", links: { recording: "#recording" } },
  { heading: "Accessible motion in practice", event: "Interface Week", location: "Porto", date: "2024-10-03", kind: "workshop", links: { slides: "#slides-a11y" } },
  { heading: "The case for boring navigation", event: "UX Meetup", location: "Berlin", date: "2024-04-18", links: { video: "#video-nav" } },
]

export default function TalkListGrouped() {
  return (
    // Items must be direct children: the list reads each one's `date` to group them.
    <TalkList groupByYear now="2026-03-02" className="mx-auto max-w-3xl [--talk-list-sticky-top:1.5rem]">
      {talks.map((talk) => (
        <TalkItem key={talk.date as string} {...talk} />
      ))}
    </TalkList>
  )
}
```

### In a Section

A “Speaking” section with a contact link for organisers. Pass `children` to add a short abstract under a talk.

```tsx
import { ArrowLink } from "@/components/portfolio/arrow-link"
import {
  Section,
  SectionContent,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import { TalkItem, TalkList } from "@/components/portfolio/talk-list"

export default function TalkListInASection() {
  return (
    <Section id="speaking" size="sm">
      <SectionHeader>
        <SectionEyebrow index={5}>Speaking</SectionEyebrow>
        <SectionTitle>Talks &amp; workshops</SectionTitle>
        <SectionDescription>
          I speak about motion, design systems and the craft of front-end. Organising an event?{" "}
          <ArrowLink href="#contact" tone="highlight">
            Get in touch
          </ArrowLink>
        </SectionDescription>
      </SectionHeader>
      <SectionContent>
        <TalkList now="2026-03-02">
          <TalkItem heading="Motion with intent" event="Frontier Conf" location="Amsterdam" date="2026-05-21" href="#motion-with-intent">
            <p className="max-w-xl text-sm leading-relaxed text-pretty text-muted-foreground">
              Animation should answer a question the user just asked. Patterns for motion that explains state, not decorates it.
            </p>
          </TalkItem>
          <TalkItem
            heading="Building a token pipeline from scratch"
            event="Systems Summit"
            location="Remote"
            date="2025-11-06"
            kind="workshop"
          >
            <p className="max-w-xl text-sm leading-relaxed text-pretty text-muted-foreground">
              A hands-on half day: from a Figma variables export to typed tokens in CSS, iOS and Android.
            </p>
          </TalkItem>
          <TalkItem
            heading="Tokens are an API"
            event="CSS Day Lisbon"
            location="Lisbon"
            date="2025-06-12"
            links={{ slides: "#slides-tokens", video: "#video-tokens" }}
          />
        </TalkList>
      </SectionContent>
    </Section>
  )
}
```

## API Reference

### TalkList

Wraps `TalkItem`s (as direct children). With `groupByYear`, items are grouped by the year of
their `date`, in the order given, under a sticky year heading.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `groupByYear` | `boolean` | `false` | Group items under a sticky year heading (offset with `--talk-list-sticky-top`, default `5rem`). |
| `now` | `Date \| string` | — | Reference date for "Upcoming" badges. Pass it (e.g. your build date) for a server render that already shows them; without it, badges use the visitor's date and appear after hydration. |
| `label` | `string` | `"Talks"` | Accessible name of the list (when not grouped by year; year lists are named by their heading). |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of each talk's title, so the list fits your page outline. With `groupByYear` the years use this level and the titles one level deeper. |
| `locale` | `string` | `"en-US"` | Locale for dates. |
| `labels` | `Partial<TalkListLabels>` | — | Built-in text, for translations: kinds (`talk`, `workshop`, `podcast`), link names (`slides`, `video`, `recording`, `event`), `upcoming`, `undated` (the year group of talks without a date) and `resources` (the accessible name of each talk's link list). |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text after external links (talk titles and resource links). |

Also accepts every `div` prop.

### UpcomingBadge

Small pill with a dot that pulses twice (four seconds), shown on talks dated after `now`. Pass children
to change the label. The word carries the meaning; the dot is decorative.

Also accepts every `span` prop.

### TalkItem

One talk, workshop or podcast appearance: date, kind, title, event and resource links.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `date` (required) | `Date \| string` | — | `Date` or ISO string, shown in a `<time>`. Dates after `now` get the "Upcoming" badge. |
| `children` | `React.ReactNode` | — | Extra content below the links (e.g. a short abstract). |
| `heading` | `React.ReactNode` | — | Talk title (the item's heading). Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `event` | `React.ReactNode` | — | Conference, meetup or show name. |
| `location` | `React.ReactNode` | — | City, "Remote", or an episode number for podcasts. |
| `kind` | `"talk" \| "workshop" \| "podcast"` | `"talk"` | Sets the icon and label above the title. |
| `kindLabel` | `React.ReactNode` | — | Override the kind's label, e.g. "Keynote" or "Panel". |
| `href` | `string` | — | Link for the title (e.g. an abstract or event page). External URLs open in a new tab and show ↗. |
| `links` | `TalkLinks` | — | Resource links shown under the event, in this order: `slides`, `video`, `recording`, `event`. Each is named after the talk for screen readers ("Slides: Tokens are an API"). |
| `now` | `Date \| string` | — | Override the list's `now`. |
| `titleAs` | `"h2" \| "h3" \| "h4" \| "h5"` | — | Heading element for the title. Defaults to the list's `headingLevel` (one deeper when grouped by year). |

Also accepts every `li` prop.

### type TalkListLabels

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `video` (required) | `string` | — |  |
| `podcast` (required) | `string` | — |  |
| `talk` (required) | `string` | — |  |
| `workshop` (required) | `string` | — |  |
| `slides` (required) | `string` | — |  |
| `recording` (required) | `string` | — |  |
| `event` (required) | `string` | — |  |
| `upcoming` (required) | `string` | — |  |
| `undated` (required) | `string` | — |  |
| `resources` (required) | `string` | — |  |

### type TalkLinks

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `video` | `string` | — |  |
| `slides` | `string` | — |  |
| `recording` | `string` | — |  |
| `event` | `string` | — |  |

## Used in templates

- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Terminal

> Terminal window for developer portfolios. When it scrolls into view, commands type themselves out (in at most 5 seconds), output lines follow and a block cursor blinks at the end.

Category: Utilities · Registry item: `@portfolio-kit/terminal` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/terminal) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/terminal.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/terminal
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/terminal.tsx` and the kit items it uses: `use-in-view`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  Terminal,
  TerminalLine,
} from "@/components/portfolio/terminal"

<Terminal heading="~/portfolio — zsh">
  <TerminalLine kind="command">whoami</TerminalLine>
  <TerminalLine>Noa Vale — design engineer, Lisbon</TerminalLine>
  <TerminalLine kind="success">Deployed to https://example.com</TerminalLine>
</Terminal>
```

## Examples

### Demo

A short shell session that types itself out when scrolled into view — commands, output, a comment and a success line.

```tsx
import { Terminal, TerminalLine } from "@/components/portfolio/terminal"

export default function TerminalDemo() {
  return (
    <Terminal heading="~/portfolio — zsh" className="w-full max-w-xl">
      <TerminalLine kind="command">whoami</TerminalLine>
      <TerminalLine>Noa Vale — design engineer, Lisbon</TerminalLine>
      <TerminalLine kind="command">cat stack.txt</TerminalLine>
      <TerminalLine>TypeScript · React · Rust · WebGL · Figma</TerminalLine>
      <TerminalLine kind="comment"># currently building design tooling at Halcyon Labs</TerminalLine>
      <TerminalLine kind="command">npm run ship</TerminalLine>
      <TerminalLine kind="success">Deployed to https://example.com in 1.84s</TerminalLine>
    </Terminal>
  )
}
```

### Card Tone, Static

`tone="card"` follows the page (light in light mode) and `animate={false}` renders the whole session at once.

```tsx
import { Terminal, TerminalLine } from "@/components/portfolio/terminal"

export default function TerminalCardTone() {
  return (
    <Terminal tone="card" animate={false} heading="git log" className="w-full max-w-xl">
      <TerminalLine kind="command">git log --oneline -3</TerminalLine>
      <TerminalLine>a41c9e2 feat: motion tokens for the kit</TerminalLine>
      <TerminalLine>7be03d1 fix: focus rings in the brutalist theme</TerminalLine>
      <TerminalLine>19f4c8a chore: ship v2.4 to production</TerminalLine>
      <TerminalLine kind="comment"># 3 commits ahead of origin/main</TerminalLine>
    </Terminal>
  )
}
```

### Install Snippet

Drop the window chrome and the idle cursor for a compact install command in docs or a project page. Prompts are customizable.

```tsx
import { Terminal, TerminalLine } from "@/components/portfolio/terminal"

export default function TerminalInstallSnippet() {
  return (
    <Terminal chrome={false} cursor={false} prompt="›" typingSpeed={28} className="w-full max-w-md">
      <TerminalLine kind="command">npx shadcn add @portfolio-kit/terminal</TerminalLine>
      <TerminalLine kind="success">Added components/terminal.tsx</TerminalLine>
    </Terminal>
  )
}
```

### In a Hero

Pair the terminal with a short intro for a developer hero — copy on the left, a live session on the right.

```tsx
import { cn } from "@/lib/utils"
import { Container } from "@/components/portfolio/section"
import { Terminal, TerminalLine } from "@/components/portfolio/terminal"
import { typography } from "@/lib/typography"

export default function TerminalInAHero() {
  return (
    <section className="py-20 md:py-28">
      <Container className="grid items-center gap-10 md:grid-cols-2 md:gap-12">
        <div className="flex flex-col gap-5">
          <p className={typography.eyebrow}>Design engineer</p>
          <h1 className={cn(typography.display, "md:text-6xl lg:text-7xl")}>I write the code behind the calm.</h1>
          <p className={typography.lead}>Interfaces, design systems and developer tools for ambitious product teams.</p>
        </div>
        <Terminal heading="hello.sh" className="min-w-0">
          <TerminalLine kind="command">git log --oneline -3</TerminalLine>
          <TerminalLine>a41c9e2 feat: motion tokens for the kit</TerminalLine>
          <TerminalLine>7be03d1 fix: focus rings in brutalist theme</TerminalLine>
          <TerminalLine>19f4c8a chore: ship v2.4 to production</TerminalLine>
          <TerminalLine kind="command">echo $STATUS</TerminalLine>
          <TerminalLine kind="success">Available for new projects</TerminalLine>
        </Terminal>
      </Container>
    </section>
  )
}
```

## API Reference

### Terminal

The window. Children are `TerminalLine`s (as direct children — they're played in order). The
sequence starts when the terminal scrolls into view and is typed only visually: the full
transcript is in the server HTML and is what screen readers, search engines and print get.
Reduced motion, `animate={false}` and a server-rendered terminal that is already on screen
when the page hydrates show it complete.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"dark" \| "card"` | `"dark"` | `dark`: a dark window in every theme, like a real terminal. `card`: uses the theme's card colors, to sit quietly on light pages. |
| `heading` | `React.ReactNode` | — | Window title in the title bar, e.g. `"~/portfolio — zsh"`. |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `chrome` | `boolean` | `true` | Show the title bar with the three window dots. Turn off for short snippets such as install commands. |
| `animate` | `boolean` | `true` | Type the sequence out. `false` (or reduced motion) renders everything at once. |
| `typingSpeed` | `number` | `42` | Milliseconds per typed character. |
| `lineDelay` | `number` | `320` | Pause before each output line appears, in ms. |
| `maxDuration` | `number` | `5000` | Longest the whole sequence may take, in ms. Longer sessions play proportionally faster so the motion stops within it (WCAG 2.2.2 asks for 5 seconds or a pause control). |
| `prompt` | `React.ReactNode` | `"$"` | Prompt shown before commands. |
| `cursor` | `boolean` | `true` | Show a final empty prompt with a cursor that blinks a few times once the sequence ends. |
| `onComplete` | `() => void` | — | Fires once the whole sequence has played (immediately when not animating). |

Also accepts every `div` prop.

### TerminalHeader

Title bar with three window dots; `children` is the centered title. Rendered by `Terminal` unless `chrome={false}`.

Also accepts every `div` prop.

### TerminalCursor

Block cursor in the accent ink color (like the prompt), readable on light and dark windows — use it on its own in any mono text.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `blink` | `boolean` | `true` | Blink four times, then stay solid (never under reduced motion). Re-mount or toggle it to blink again. |

Also accepts every `span` prop.

### TerminalLine

One line of the session. `command` lines type out character by character
(when their content is plain text); other kinds appear after `lineDelay`.
The full text is always in the DOM for assistive tech and search engines.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `"command" \| "output" \| "comment" \| "success"` | `"output"` | `command` gets the prompt and types out (plain-text children only); `output` and `comment` (muted) fade in; `success` adds a ✓ in the success color. |
| `prompt` | `React.ReactNode` | — | Override the terminal prompt for this command. |
| `delay` | `number` | `0` | Extra pause before this line starts, in ms. |

Also accepts every `div` prop.



---

# Testimonial Card

> Client quote with author (avatar or initials), optional star rating and source link, shown as a card, a plain block or a large featured quote.

Category: Social Proof · Registry item: `@portfolio-kit/testimonial-card` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/testimonial-card) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/testimonial-card.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/testimonial-card
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/testimonial-card.tsx` and the kit items it uses: `typography`.

npm dependencies: `class-variance-authority`, `lucide-react`.

## Usage

```tsx
import {
  TestimonialAuthor,
  TestimonialCard,
  TestimonialHeader,
  TestimonialQuote,
  TestimonialRating,
  TestimonialSource,
} from "@/components/portfolio/testimonial-card"

<TestimonialCard>
  <TestimonialHeader>
    <TestimonialRating value={5} />
    <TestimonialSource href="https://example.com/review" label="LinkedIn" />
  </TestimonialHeader>
  <TestimonialQuote>
    <p>We came for a landing page and left with a brand system our whole team uses.</p>
  </TestimonialQuote>
  <TestimonialAuthor name="Lena Brandt" position="Head of Marketing" company="Northpeak" />
</TestimonialCard>
```

## Examples

### Demo

A client quote with a star rating, where it was posted, and who said it.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  TestimonialAuthor,
  TestimonialCard,
  TestimonialHeader,
  TestimonialQuote,
  TestimonialRating,
  TestimonialSource,
} from "@/components/portfolio/testimonial-card"

const author = { name: "Lena Brandt", role: "Head of Marketing", company: "Northpeak" }

export default function TestimonialCardDemo() {
  return (
    <TestimonialCard className="w-full max-w-md">
      <TestimonialHeader>
        <TestimonialRating value={5} />
        <TestimonialSource href="https://example.com" label="LinkedIn" />
      </TestimonialHeader>
      <TestimonialQuote glyph={false}>
        <p>We came for a landing page and left with a brand system our whole team actually uses.</p>
      </TestimonialQuote>
      <TestimonialAuthor
        name={author.name}
        position={author.role}
        company={author.company}
        avatar={<GenerativeArt seed={author.name} variant="portrait" grain={false} />}
      />
    </TestimonialCard>
  )
}
```

### Featured

One big quote in heading type. Use it once per page, for the testimonial that matters most.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  TestimonialAuthor,
  TestimonialCard,
  TestimonialQuote,
  TestimonialSource,
} from "@/components/portfolio/testimonial-card"

const author = { name: "Tomas Reyes", role: "Founder", company: "Fieldnote" }

export default function TestimonialCardFeatured() {
  return (
    <TestimonialCard variant="featured" className="mx-auto max-w-4xl">
      <TestimonialQuote>
        <p>Fast, thoughtful and genuinely fun to work with. The prototype Noa built in week one became the product.</p>
      </TestimonialQuote>
      <TestimonialAuthor
        name={author.name}
        position={author.role}
        company={author.company}
        avatar={<GenerativeArt seed={author.name} variant="portrait" grain={false} />}
      >
        <TestimonialSource href="https://example.com" label="LinkedIn" className="ml-auto self-end max-sm:hidden" />
      </TestimonialAuthor>
    </TestimonialCard>
  )
}
```

### Plain

No card chrome: quotes sit directly on the page, in a row under a section or beside a case study.

```tsx
import { TestimonialAuthor, TestimonialCard, TestimonialQuote } from "@/components/portfolio/testimonial-card"

const testimonials = [
  {
    quote: "The most detail-oriented engineer I've worked with. Every interaction just feels right.",
    name: "Priya Anand",
    role: "Design Director",
    company: "Orbit",
  },
  {
    quote: "They turned a messy brief into a clear, beautiful site — and taught our team a lot along the way.",
    name: "Sam Okafor",
    role: "Owner",
    company: "Kiln Ceramics",
  },
  {
    quote: "Clear communication, zero drama, and a codebase we were proud to inherit.",
    name: "Diego Marín",
    role: "CTO",
    company: "Atlas & Co",
  },
]

export default function TestimonialCardPlain() {
  return (
    <div className="mx-auto grid max-w-5xl gap-10 md:grid-cols-3 md:gap-8">
      {testimonials.map((t) => (
        <TestimonialCard key={t.name} variant="plain">
          <TestimonialQuote>
            <p>{t.quote}</p>
          </TestimonialQuote>
          <TestimonialAuthor name={t.name} position={t.role} company={t.company} />
        </TestimonialCard>
      ))}
    </div>
  )
}
```

### Wall of Love

A masonry wall of mixed-length quotes using CSS columns, with ratings, sources and avatars where you have them.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  TestimonialAuthor,
  TestimonialCard,
  TestimonialHeader,
  TestimonialQuote,
  TestimonialQuoteGlyph,
  TestimonialRating,
  TestimonialSource,
} from "@/components/portfolio/testimonial-card"

type Testimonial = {
  quote: string
  name: string
  role: string
  company: string
  rating?: number
  source?: string
  avatar?: boolean
}

const testimonials: Testimonial[] = [
  {
    quote:
      "Noa has a rare ability to hold the whole product in their head — from the grid to the database schema. Our design system finally feels like one thing.",
    name: "Ines Carvalho",
    role: "VP Product",
    company: "Halcyon Labs",
    rating: 5,
    avatar: true,
  },
  { quote: "Shipped on time. Twice.", name: "Hana Kobayashi", role: "PM", company: "Tidewater Energy", source: "Clutch" },
  {
    quote: "Our conversion rate went up 38% the month the new site launched. The animations are the cherry on top.",
    name: "Ruth Adeyemi",
    role: "Co-founder",
    company: "Meridian",
    rating: 5,
    source: "Google",
  },
  {
    quote: "Clear communication, zero drama, and a codebase we were proud to inherit. Every handover note answered a question before we asked it.",
    name: "Diego Marín",
    role: "CTO",
    company: "Atlas & Co",
    avatar: true,
  },
  {
    quote: "Fast, thoughtful and genuinely fun to work with. The prototype built in week one became the product.",
    name: "Tomas Reyes",
    role: "Founder",
    company: "Fieldnote",
    source: "LinkedIn",
  },
  {
    quote: "They turned a messy brief into a clear, beautiful site — and taught our team a lot along the way.",
    name: "Sam Okafor",
    role: "Owner",
    company: "Kiln Ceramics",
    rating: 4.5,
  },
]

export default function TestimonialCardWall() {
  return (
    <div className="mx-auto max-w-5xl columns-1 gap-4 sm:columns-2 md:gap-6 lg:columns-3 [&>*]:mb-4 [&>*]:break-inside-avoid md:[&>*]:mb-6">
      {testimonials.map((t) => (
        <TestimonialCard key={t.name}>
          <TestimonialHeader>
            {t.rating ? <TestimonialRating value={t.rating} /> : <TestimonialQuoteGlyph className="size-6" />}
            {t.source && <TestimonialSource href="https://example.com" label={t.source} />}
          </TestimonialHeader>
          <TestimonialQuote glyph={false}>
            <p>{t.quote}</p>
          </TestimonialQuote>
          <TestimonialAuthor
            name={t.name}
            position={t.role}
            company={t.company}
            avatar={t.avatar ? <GenerativeArt seed={t.name} variant="portrait" grain={false} /> : undefined}
          />
        </TestimonialCard>
      ))}
    </div>
  )
}
```

## API Reference

### TestimonialCard

A `<figure>` holding a `TestimonialQuote` and a `TestimonialAuthor` (plus an optional `TestimonialHeader`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"card" \| "plain" \| "featured"` | `"card"` | `card`: bordered card for grids and walls. `plain`: no chrome, for a quote inside other content. `featured`: one large quote as a section of its own. |
| `size` | `"default" \| "lg"` | — | Quote scale. Defaults to `lg` for `featured` and `default` otherwise; use `lg` with `plain` for big quotes without card chrome. |

Also accepts every `figure` prop.

### TestimonialQuoteGlyph

Filled double quote mark. Decorative; inherits `currentColor`.

Also accepts every `svg` prop.

### TestimonialQuote

The quote itself. Pass one or more `<p>` as children; size follows the card's `size`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `glyph` | `boolean` | `true` | Show the decorative quote mark above the text. |

Also accepts every `blockquote` prop.

### TestimonialAuthor

Avatar, name (in a `<cite>`) and position as the `<figcaption>`. The avatar is decorative because
the name sits beside it. Extra `children` sit at the end of the row (e.g. a `TestimonialSource`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Who said it. Also used for the initials fallback. |
| `position` | `React.ReactNode` | — | Job title or position, e.g. "VP Product". |
| `company` | `React.ReactNode` | — | Company, appended to the position with a comma. |
| `avatar` | `string \| React.ReactNode` | — | Image URL, or any node (e.g. `<GenerativeArt variant="portrait" />`). Falls back to initials. |
| `initials` | `string` | — | Override the auto-generated initials. |

Also accepts every `figcaption` prop.

### TestimonialAvatar

Round avatar: image, custom node, or initials on `muted`. Decorative (hidden from screen readers): always render the name next to it. Used by `TestimonialAuthor` and the spotlight.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Person's name, used for the initials fallback. |
| `avatar` | `string \| React.ReactNode` | — | Image URL, or any node (e.g. `<GenerativeArt variant="portrait" />`). Falls back to initials. |
| `initials` | `string` | — | Override the auto-generated initials. |

Also accepts every `span` prop.

### TestimonialRating

Star rating. Screen readers hear the `label` text; the stars are hidden from them. Filled stars
use the accent, empty ones are outlines, so the count doesn't depend on colour alone.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` | — | Rating value, e.g. `5` or `4.5`. Stars round to the nearest half; the label keeps the exact value. |
| `max` | `number` | `5` | Number of stars. |
| `label` | `(value: number, max: number) => string` | `defaultRatingLabel` | Screen-reader text; receives the clamped value and `max`. Defaults to "Rated 4.5 out of 5 stars". |

Also accepts every `div` prop.

### TestimonialSource

Where the quote came from. A link if `href` is set (external links open in a new tab, show ↗ and
tell screen readers), plain text otherwise.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `React.ReactNode` | — | Where the quote was published, e.g. "LinkedIn". Rendered as "via LinkedIn". Pass `children` to write your own text. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added to external links, which open in a new tab. |

Also accepts every `a` prop.

### TestimonialHeader

Row above the quote for a `TestimonialRating` and/or `TestimonialSource`. A lone source aligns right.

Also accepts every `div` prop.

## Used in templates

- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)
- [Designer](https://www.parthjadhav.com/products/portfolio-kit/templates/designer.md)
- [Freelancer](https://www.parthjadhav.com/products/portfolio-kit/templates/freelancer.md)
- [Speaker](https://www.parthjadhav.com/products/portfolio-kit/templates/speaker.md)
- [Writer](https://www.parthjadhav.com/products/portfolio-kit/templates/writer.md)



---

# Testimonial Spotlight

> One large quote at a time with prev/next, dots or author tabs, and optional autoplay that pauses on hover, focus and reduced motion.

Category: Social Proof · Registry item: `@portfolio-kit/testimonial-spotlight` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/testimonial-spotlight) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/testimonial-spotlight.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/testimonial-spotlight
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/testimonial-spotlight.tsx` and the kit items it uses: `testimonial-card`, `use-composed-refs`, `use-in-view`, `use-page-visible`, `use-reduced-motion`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import {
  TestimonialAuthor,
  TestimonialCard,
  TestimonialQuote,
} from "@/components/portfolio/testimonial-card"
import {
  TestimonialSpotlight,
  TestimonialSpotlightControls,
  TestimonialSpotlightDots,
  TestimonialSpotlightNext,
  TestimonialSpotlightPrevious,
  TestimonialSpotlightSlide,
  TestimonialSpotlightViewport,
} from "@/components/portfolio/testimonial-spotlight"

<TestimonialSpotlight>
  <TestimonialSpotlightViewport>
    <TestimonialSpotlightSlide>
      <TestimonialCard variant="plain" size="lg">
        <TestimonialQuote>
          <p>Noa turned a vague brief into a product our users love.</p>
        </TestimonialQuote>
        <TestimonialAuthor name="Ada Reyes" position="Head of Product" company="Halcyon Labs" />
      </TestimonialCard>
    </TestimonialSpotlightSlide>
  </TestimonialSpotlightViewport>
  <TestimonialSpotlightControls>
    <TestimonialSpotlightPrevious />
    <TestimonialSpotlightNext />
    <TestimonialSpotlightDots />
  </TestimonialSpotlightControls>
</TestimonialSpotlight>
```

## Examples

### Demo

One large quote at a time with previous/next, a counter and dots. Arrow keys work once focus is inside, and touch screens can swipe.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  TestimonialAuthor,
  TestimonialCard,
  TestimonialQuote,
} from "@/components/portfolio/testimonial-card"
import {
  TestimonialSpotlight,
  TestimonialSpotlightControls,
  TestimonialSpotlightCount,
  TestimonialSpotlightDots,
  TestimonialSpotlightNext,
  TestimonialSpotlightPrevious,
  TestimonialSpotlightSlide,
  TestimonialSpotlightViewport,
} from "@/components/portfolio/testimonial-spotlight"

const testimonials = [
  {
    quote:
      "Noa has a rare ability to hold the whole product in their head — from the grid to the database schema. Our design system finally feels like one thing.",
    name: "Ines Carvalho",
    role: "VP Product",
    company: "Halcyon Labs",
  },
  {
    quote: "Fast, thoughtful and genuinely fun to work with. The prototype Noa built in week one became the product.",
    name: "Tomas Reyes",
    role: "Founder",
    company: "Fieldnote",
  },
  {
    quote: "The most detail-oriented engineer I've worked with. Every interaction just feels right.",
    name: "Priya Anand",
    role: "Design Director",
    company: "Orbit",
  },
  {
    quote: "They turned a messy brief into a clear, beautiful site — and taught our team a lot along the way.",
    name: "Sam Okafor",
    role: "Owner",
    company: "Kiln Ceramics",
  },
]

export default function TestimonialSpotlightDemo() {
  return (
    <TestimonialSpotlight className="mx-auto max-w-4xl">
      <TestimonialSpotlightViewport>
        {testimonials.map((t) => (
          <TestimonialSpotlightSlide key={t.name}>
            <TestimonialCard variant="plain" size="lg">
              <TestimonialQuote>
                <p>{t.quote}</p>
              </TestimonialQuote>
              <TestimonialAuthor
                name={t.name}
                position={t.role}
                company={t.company}
                avatar={<GenerativeArt seed={t.name} variant="portrait" grain={false} />}
              />
            </TestimonialCard>
          </TestimonialSpotlightSlide>
        ))}
      </TestimonialSpotlightViewport>
      <TestimonialSpotlightControls className="border-t pt-6">
        <TestimonialSpotlightPrevious />
        <TestimonialSpotlightNext />
        <TestimonialSpotlightCount className="ml-2" />
        <TestimonialSpotlightDots className="ml-auto" />
      </TestimonialSpotlightControls>
    </TestimonialSpotlight>
  )
}
```

### Author Tabs

Autoplay with a row of authors as tabs. The active tab fills with progress; hover, focus or the pause button stop the clock.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  TestimonialCard,
  TestimonialQuote,
  TestimonialQuoteGlyph,
} from "@/components/portfolio/testimonial-card"
import {
  TestimonialSpotlight,
  TestimonialSpotlightAuthor,
  TestimonialSpotlightAuthors,
  TestimonialSpotlightPlayToggle,
  TestimonialSpotlightSlide,
  TestimonialSpotlightViewport,
} from "@/components/portfolio/testimonial-spotlight"

const testimonials = [
  {
    quote: "Our design system finally feels like one thing, and the team actually enjoys using it.",
    name: "Ines Carvalho",
    role: "VP Product, Halcyon",
  },
  {
    quote: "The prototype built in week one became the product. We still ship on top of it today.",
    name: "Tomas Reyes",
    role: "Founder, Fieldnote",
  },
  {
    quote: "The most detail-oriented engineer I've worked with. Every interaction just feels right.",
    name: "Priya Anand",
    role: "Design lead, Orbit",
  },
  {
    quote: "They turned a messy brief into a clear, beautiful site — and taught our team a lot along the way.",
    name: "Sam Okafor",
    role: "Owner, Kiln",
  },
]

export default function TestimonialSpotlightAuthorTabs() {
  return (
    <TestimonialSpotlight autoplay={8000} className="mx-auto max-w-4xl">
      <div className="flex flex-col gap-6 md:gap-8">
        <div className="flex items-start justify-between gap-4">
          <TestimonialQuoteGlyph className="size-10 md:size-14" />
          <TestimonialSpotlightPlayToggle />
        </div>
        <TestimonialSpotlightViewport>
          {testimonials.map((t) => (
            <TestimonialSpotlightSlide key={t.name}>
              <TestimonialCard variant="plain" size="lg">
                <TestimonialQuote glyph={false}>
                  <p>{t.quote}</p>
                </TestimonialQuote>
              </TestimonialCard>
            </TestimonialSpotlightSlide>
          ))}
        </TestimonialSpotlightViewport>
      </div>
      <TestimonialSpotlightAuthors>
        {testimonials.map((t) => (
          <TestimonialSpotlightAuthor
            key={t.name}
            name={t.name}
            position={t.role}
            avatar={<GenerativeArt seed={t.name} variant="portrait" grain={false} />}
          />
        ))}
      </TestimonialSpotlightAuthors>
    </TestimonialSpotlight>
  )
}
```

### In a Card

The carousel in card chrome with the controls in a footer bar, as a self-contained block for dense pages.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  TestimonialAuthor,
  TestimonialCard,
  TestimonialQuote,
} from "@/components/portfolio/testimonial-card"
import {
  TestimonialSpotlight,
  TestimonialSpotlightControls,
  TestimonialSpotlightCount,
  TestimonialSpotlightNext,
  TestimonialSpotlightPrevious,
  TestimonialSpotlightSlide,
  TestimonialSpotlightViewport,
} from "@/components/portfolio/testimonial-spotlight"

const testimonials = [
  {
    quote: "Clear communication, zero drama, and a codebase we were proud to inherit.",
    name: "Diego Marín",
    role: "CTO",
    company: "Atlas & Co",
  },
  {
    quote: "Our conversion rate went up 38% the month the new site launched. The animations are the cherry on top.",
    name: "Ruth Adeyemi",
    role: "Co-founder",
    company: "Meridian",
  },
  {
    quote: "Shipped on time. Twice. I'd hire them again tomorrow.",
    name: "Hana Kobayashi",
    role: "Product Manager",
    company: "Tidewater Energy",
  },
]

export default function TestimonialSpotlightCarded() {
  return (
    <TestimonialSpotlight className="mx-auto max-w-3xl gap-0 overflow-hidden rounded-2xl border bg-card shadow-card md:gap-0">
      <TestimonialSpotlightViewport className="p-6 sm:p-8 md:p-10">
        {testimonials.map((t) => (
          <TestimonialSpotlightSlide key={t.name}>
            <TestimonialCard variant="plain" size="lg">
              <TestimonialQuote>
                <p>{t.quote}</p>
              </TestimonialQuote>
              <TestimonialAuthor
                name={t.name}
                position={t.role}
                company={t.company}
                avatar={<GenerativeArt seed={t.name} variant="portrait" grain={false} />}
              />
            </TestimonialCard>
          </TestimonialSpotlightSlide>
        ))}
      </TestimonialSpotlightViewport>
      <TestimonialSpotlightControls className="justify-between border-t bg-muted/40 px-6 py-4 sm:px-8 md:px-10">
        <TestimonialSpotlightCount />
        <div className="flex gap-2">
          <TestimonialSpotlightPrevious />
          <TestimonialSpotlightNext />
        </div>
      </TestimonialSpotlightControls>
    </TestimonialSpotlight>
  )
}
```

## API Reference

### TestimonialSpotlight

The carousel root (`<section aria-roledescription="carousel">`). ←/→ move
between slides while focus is inside (mirrored in right-to-left layouts).
Slide changes the visitor makes are announced politely; autoplay changes are not.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean \| number` | `false` | Rotate automatically. `true` uses 7s; a number sets the interval in ms. Add a `TestimonialSpotlightPlayToggle` so visitors can stop it (WCAG 2.2.2). Off under reduced motion until the visitor presses play; paused while hovered, while a control has focus, when scrolled out of view and when the tab is hidden. |
| `defaultIndex` | `number` | `0` | Starting slide (uncontrolled). |
| `index` | `number` | — | Controlled slide index. |
| `onIndexChange` | `(index: number) => void` | — | Called with the new index when the slide changes (buttons, dots, keys, swipe or autoplay). |
| `label` | `string` | `"Testimonials"` | Accessible name of the carousel region. |
| `labels` | `Partial<TestimonialSpotlightLabels>` | — | The built-in strings of every part (roles, slide names, button names), to translate them. |

Also accepts every `section` prop.

### TestimonialSpotlightViewport

Holds the `TestimonialSpotlightSlide`s (direct children, a `.map()` is fine), stacked in one grid
cell so the height never jumps between short and long quotes (it's the tallest slide). Swipe
sideways on touch screens to change slide. It is the polite live region for slide changes the
visitor makes; it stays silent while autoplay runs.

Also accepts every `div` prop.

### TestimonialSpotlightSlide

One slide. Put a `TestimonialCard` (e.g. `variant="plain" size="lg"`) inside. Inactive slides
are hidden and inert. Named "2 of 4" by default (the root's `labels.slidePosition`, or pass `aria-label`); it is a tab
panel when `TestimonialSpotlightDots` or `TestimonialSpotlightAuthors` is present, a group otherwise.

Also accepts every `div` prop.

### TestimonialSpotlightControls

Layout row for prev/next, count, dots and play/pause.

Also accepts every `div` prop.

### TestimonialSpotlightPrevious

Previous-slide button (wraps around). Children replace the arrow icon. Its name is `labels.previous` on the root ("Previous testimonial"), or pass `aria-label`.

Also accepts every `button` prop.

### TestimonialSpotlightNext

Next-slide button (wraps around). Children replace the arrow icon. Its name is `labels.next` on the root ("Next testimonial"), or pass `aria-label`.

Also accepts every `button` prop.

### TestimonialSpotlightPlayToggle

Play/pause toggle. Renders nothing unless `autoplay` is set on the root. Include it whenever
autoplay is on so visitors can stop the rotation. Focusing it doesn't pause the timer.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pauseLabel` | `string` | — | Accessible name while autoplay runs. Default: the root's `labels.pause` ("Pause autoplay"). |
| `playLabel` | `string` | — | Accessible name while autoplay is stopped. Default: the root's `labels.play` ("Start autoplay"). |

Also accepts every `button` prop.

### TestimonialSpotlightCount

"02 / 05" counter. Invisible (space kept) until the slides are counted after mount.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `(position: number, count: number) => string` | — | Screen-reader text for the visible "02 / 05"; receives the 1-based position and the total. Default: the root's `labels.count` ("Testimonial 2 of 5"). |

Also accepts every `p` prop.

### TestimonialSpotlightDots

One tab per slide (APG tabs: one Tab stop, ←/→ and Home/End choose). The active dot stretches
and fills with autoplay progress. Hidden with fewer than two slides. Name the list with
`aria-label` (default: the root's `labels.choose`, "Choose testimonial").

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tabLabel` | `(position: number, count: number) => string` | — | Accessible name of each dot; receives the 1-based position and the total. Default: the root's `labels.tab` ("Testimonial 2"). |

Also accepts every `div` prop.

### TestimonialSpotlightAuthors

Tab list of authors (avatar, name, position) that jumps to their quote (APG tabs: one Tab stop,
←/→ and Home/End choose). Children: `TestimonialSpotlightAuthor`, in slide order. Name the list
with `aria-label` (default: the root's `labels.choose`, "Choose testimonial").

Also accepts every `div` prop.

### TestimonialSpotlightAuthor

One author tab, matched to the slide at the same position. The rule above it fills with autoplay progress.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Author name. Also used for the initials fallback. |
| `position` | `React.ReactNode` | — | Job title or position, shown under the name. |
| `avatar` | `string \| React.ReactNode` | — | Image URL or node; falls back to initials. |

Also accepts every `button` prop.

### type TestimonialSpotlightLabels

Every built-in string, to translate them in one place. `{index}` and `{count}` are replaced with the
1-based position and the number of slides. A part's own prop (`aria-label`, `pauseLabel`…) still wins.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `carousel` (required) | `string` | — | Announced role of the root ("carousel"). |
| `slide` (required) | `string` | — | Announced role of each slide ("slide"). |
| `slidePosition` (required) | `string` | — | Name of each slide: "{index} of {count}". |
| `previous` (required) | `string` | — | `TestimonialSpotlightPrevious`: "Previous testimonial". |
| `next` (required) | `string` | — | `TestimonialSpotlightNext`: "Next testimonial". |
| `pause` (required) | `string` | — | `TestimonialSpotlightPlayToggle` while autoplay runs: "Pause autoplay". |
| `play` (required) | `string` | — | `TestimonialSpotlightPlayToggle` while autoplay is stopped: "Start autoplay". |
| `count` (required) | `string` | — | `TestimonialSpotlightCount`'s spoken text: "Testimonial {index} of {count}". |
| `choose` (required) | `string` | — | Name of the dots and authors tab lists: "Choose testimonial". |
| `tab` (required) | `string` | — | Name of each dot: "Testimonial {index}". |



---

# Text Reveal

> Splits a headline into words or characters that slide up from a mask, staggered, when it scrolls into view. The original text stays accessible.

Category: Effects · Registry item: `@portfolio-kit/text-reveal` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/text-reveal) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/text-reveal.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/text-reveal
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/text-reveal.tsx` and the kit items it uses: `use-composed-refs`, `use-in-view`, `use-mount-check`, `use-reduced-motion`.

## Usage

```tsx
import { TextReveal } from "@/components/portfolio/text-reveal"
```

## Examples

### Demo

A short manifesto whose words slide up out of a mask one after another, then numbered lines that reveal as they scroll into view. Scroll the preview.

```tsx
import { cn } from "@/lib/utils"
import { Section } from "@/components/portfolio/section"
import { TextReveal } from "@/components/portfolio/text-reveal"
import { typography } from "@/lib/typography"

const lines = ["Research, slowly.", "Design, deliberately.", "Build, carefully.", "Ship, then listen."]

export default function TextRevealDemo() {
  return (
    <Section>
      <p className={typography.eyebrow}>How I work</p>
      <TextReveal as="h2" delay={200} className={cn(typography.title, "mt-4 max-w-3xl")}>
        Quietly ambitious interfaces for teams who sweat the details — from the first rough sketch to the last pull
        request, and every small, careful moment in between.
      </TextReveal>
      <p className={cn(typography.meta, "mt-8")}>Scroll down ↓</p>
      <ol role="list" className="mt-[35vh] flex flex-col gap-[35vh] pb-[20vh]">
        {lines.map((line, i) => (
          <li key={line} className="flex flex-col gap-4">
            <span className={cn(typography.meta, "text-highlight-ink")}>{String(i + 1).padStart(2, "0")}</span>
            <TextReveal as="p" className={typography.display}>
              {line}
            </TextReveal>
          </li>
        ))}
      </ol>
    </Section>
  )
}
```

### Characters

`split="char"` staggers every letter for short section titles; words still never break mid-word.

```tsx
import { SectionEyebrow, SectionHeader } from "@/components/portfolio/section"
import { TextReveal } from "@/components/portfolio/text-reveal"
import { typography } from "@/lib/typography"

export default function TextRevealCharacters() {
  return (
    <SectionHeader className="mx-auto max-w-4xl py-12 md:py-20">
      <SectionEyebrow index={2}>Work</SectionEyebrow>
      <TextReveal as="h2" split="char" className={typography.title}>
        Selected work, 2019 — 2025
      </TextReveal>
    </SectionHeader>
  )
}
```

### Paragraph

Longer copy with a tight `stagger` and shorter `duration`, so an intro paragraph ripples in instead of crawling.

```tsx
import { TextReveal } from "@/components/portfolio/text-reveal"
import { typography } from "@/lib/typography"

export default function TextRevealParagraph() {
  return (
    <div className="mx-auto flex max-w-2xl flex-col gap-6 py-12 md:py-20">
      <TextReveal as="h2" className={typography.heading}>
        About
      </TextReveal>
      <TextReveal as="p" stagger={18} duration={700} delay={150} className={typography.lead}>
        I&apos;m a design engineer working at the seam between product design and front-end engineering. For the last
        nine years I&apos;ve helped startups and studios turn rough ideas into interfaces that feel inevitable.
      </TextReveal>
    </div>
  )
}
```

## API Reference

### TextReveal

Slides each word (or character) up out of its own mask when the text scrolls into view (or,
for a short line at the very end of the page, once it is wholly visible). Screen readers get
the original string once; with reduced motion it's shown as-is; it always prints; and
server-rendered HTML reveals itself with CSS after two seconds if JavaScript never runs. The
masks are removed once the last unit lands, so descenders and accents are never clipped at rest.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `string` | — | The text to split. Whitespace is preserved as natural break points. |
| `as` | `"h1" \| "h2" \| "h3" \| "h4" \| "p" \| "span" \| "div"` | `"p"` | Element to render — pick the right heading level for the page outline. |
| `split` | `"word" \| "char"` | `"word"` | Animate each word, or each character (words still never break mid-word). |
| `stagger` | `number` | — | Delay between units in ms. Defaults to 70 for words, 22 for characters. |
| `delay` | `number` | `0` | Delay before the first unit, in ms. |
| `duration` | `number` | `900` | Duration of each unit's slide, in ms. |
| `repeat` | `boolean` | `false` | Animate again every time the text re-enters the viewport. |

Also accepts every `p` prop.

## Used in templates

- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)



---

# Theme Picker

> Switch between `data-theme` presets with round color swatches or a labelled list, on <html> or any element, and optionally remember the choice.

Category: Navigation · Registry item: `@portfolio-kit/theme-picker` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/theme-picker) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/theme-picker.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/theme-picker
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/theme-picker.tsx`.

npm dependencies: `class-variance-authority`, `lucide-react`, `radix-ui`.

## Usage

```tsx
import {
  ThemePicker,
  ThemePickerItem,
} from "@/components/portfolio/theme-picker"

<ThemePicker defaultValue="light" storageKey="site-theme">
  <ThemePickerItem value="light" label="Light" />
  <ThemePickerItem value="dark" label="Dark" />
  <ThemePickerItem value="paper" label="Paper" swatches={["#f4efe6", "#1c1a17", "#c2410c"]} />
</ThemePicker>
```

## Examples

### Demo

Round swatches that set `data-theme` on the page. Define each theme as CSS variables under `[data-theme="…"]`; the swatches read their colors from them. Try it: this preview re-themes.

```tsx
import { ThemePicker } from "@/components/portfolio/theme-picker"

// Usually lives in globals.css. Any token you leave out falls back to your :root theme.
const css = `
[data-theme="paper"] { --background: oklch(0.975 0.01 80); --foreground: oklch(0.2 0.02 60); --card: oklch(0.99 0.006 80); --muted: oklch(0.94 0.013 80); --muted-foreground: oklch(0.5 0.03 70); --border: oklch(0.87 0.017 80); --highlight: oklch(0.55 0.13 38); --highlight-ink: oklch(0.55 0.13 38); }
[data-theme="night"] { --background: oklch(0.16 0.02 270); --foreground: oklch(0.96 0.01 270); --card: oklch(0.2 0.025 270); --muted: oklch(0.24 0.03 270); --muted-foreground: oklch(0.74 0.03 270); --border: oklch(0.3 0.03 270); --highlight: oklch(0.8 0.13 210); --highlight-ink: oklch(0.8 0.13 210); --primary: oklch(0.93 0.01 270); --primary-foreground: oklch(0.16 0.02 270); color-scheme: dark; }
[data-theme="forest"] { --background: oklch(0.97 0.012 150); --foreground: oklch(0.22 0.03 155); --card: oklch(0.99 0.006 150); --muted: oklch(0.94 0.018 150); --muted-foreground: oklch(0.47 0.04 155); --border: oklch(0.88 0.02 150); --highlight: oklch(0.52 0.13 155); --highlight-ink: oklch(0.52 0.13 155); }
`

// `default` is the :root theme, which has no [data-theme] rule of its own, so its swatch would show
// whichever theme is active. Fixed colors (surface, ink, accent) keep it a preview of the default.
const themes = [
  { value: "default", label: "Default", swatches: ["oklch(1 0 0)", "oklch(0.16 0 0)", "oklch(0.57 0.21 262)"] },
  { value: "paper", label: "Paper" },
  { value: "night", label: "Night" },
  { value: "forest", label: "Forest" },
]

export default function ThemePickerDemo() {
  return (
    <>
      <style>{css}</style>
      <ThemePicker themes={themes} defaultValue="default" className="pt-8" />
    </>
  )
}
```

### List

The `list` variant adds names and one-line descriptions — at home in a settings panel or a header dropdown. Pass `swatches` to show fixed colors instead of reading CSS variables.

```tsx
import { ThemePicker } from "@/components/portfolio/theme-picker"

const themes = [
  { value: "default", label: "Default", description: "Neutral grays, blue accent", swatches: ["oklch(1 0 0)", "oklch(0.16 0 0)", "oklch(0.57 0.21 262)"] },
  { value: "paper", label: "Paper", description: "Warm off-white, terracotta", swatches: ["oklch(0.975 0.01 80)", "oklch(0.2 0.02 60)", "oklch(0.55 0.13 38)"] },
  { value: "night", label: "Night", description: "Deep blue-black, cyan", swatches: ["oklch(0.16 0.02 270)", "oklch(0.96 0.01 270)", "oklch(0.8 0.13 210)"] },
]

export default function ThemePickerList() {
  return <ThemePicker variant="list" themes={themes} target={null} defaultValue="default" className="w-full max-w-72" />
}
```

### Scoped Preview

Point `target` at an element to theme just that element — handy for “try it” previews. The rest of the page is untouched.

```tsx
import * as React from "react"

import { buttonVariants } from "@/components/ui/button"
import { cn } from "@/lib/utils"
import { ThemePicker } from "@/components/portfolio/theme-picker"
import { typography } from "@/lib/typography"

// Usually lives in globals.css. Any token you leave out falls back to your :root theme.
const css = `
[data-theme="paper"] { --background: oklch(0.975 0.01 80); --foreground: oklch(0.2 0.02 60); --muted-foreground: oklch(0.5 0.03 70); --border: oklch(0.87 0.017 80); --primary: oklch(0.55 0.13 38); --primary-foreground: oklch(0.99 0 0); --highlight: oklch(0.55 0.13 38); --highlight-ink: oklch(0.55 0.13 38); --font-heading: ui-serif, Georgia, serif; --heading-weight: 400; --radius: 0.25rem; }
[data-theme="night"] { --background: oklch(0.16 0.02 270); --foreground: oklch(0.96 0.01 270); --muted-foreground: oklch(0.74 0.03 270); --border: oklch(0.3 0.03 270); --primary: oklch(0.8 0.13 210); --primary-foreground: oklch(0.16 0.02 270); --highlight: oklch(0.8 0.13 210); --highlight-ink: oklch(0.8 0.13 210); --radius: 1rem; }
[data-theme="block"] { --background: oklch(0.985 0 0); --foreground: oklch(0 0 0); --muted-foreground: oklch(0.4 0 0); --border: oklch(0 0 0); --primary: oklch(0 0 0); --primary-foreground: oklch(1 0 0); --highlight: oklch(0.88 0.2 125); --highlight-ink: oklch(0.45 0.13 135); --card-shadow: 4px 4px 0 0 oklch(0 0 0); --radius: 0rem; }
`

const themes = [
  { value: "paper", label: "Paper" },
  { value: "night", label: "Night" },
  { value: "block", label: "Block" },
]

export default function ThemePickerScoped() {
  const previewRef = React.useRef<HTMLDivElement>(null)
  const [theme, setTheme] = React.useState("paper")

  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-10">
      <style>{css}</style>
      <div
        ref={previewRef}
        className="flex w-full flex-col gap-4 rounded-2xl border bg-background p-6 text-foreground shadow-card transition-colors duration-300"
      >
        <p className={cn(typography.meta, "text-pretty")}>
          <span className="text-highlight-ink">Now</span> · Taking on two projects for spring
        </p>
        <p className="font-heading text-3xl leading-[1.05]">Calm, fast interfaces.</p>
        <p className="text-sm text-muted-foreground">Design engineer based in Lisbon.</p>
        <a href="#contact" className={cn(buttonVariants({ size: "sm" }), "w-fit rounded-pill px-4")}>
          Get in touch
        </a>
      </div>
      <ThemePicker themes={themes} target={previewRef} value={theme} onValueChange={setTheme} label="Preview theme" />
    </div>
  )
}
```

## API Reference

### ThemePicker

A radio group of themes that sets `data-theme` (or your `attribute`) on `<html>` or any target, and can
remember the choice. Pass `themes` for the quick version, or compose `ThemePickerItem`s.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"swatches" \| "list"` | `"swatches"` | `swatches`: a row of round color dots, for headers. `list`: a card of rows with name, swatches and description, for settings menus. |
| `themes` | `ThemeOption[]` | — | Convenience: render one item per theme. Or compose `ThemePickerItem`s as children. |
| `value` | `string` | — | The selected theme (controlled). |
| `defaultValue` | `string` | — | The theme selected on first render (uncontrolled). A choice stored under `storageKey` wins. |
| `onValueChange` | `(value: string) => void` | — | Called with the theme name when the choice changes. |
| `target` | `"html" \| HTMLElement \| React.RefObject<HTMLElement \| null> \| null` | `"html"` | Element that receives the attribute: `"html"`, an element, a ref, or `null` to not touch the DOM. |
| `attribute` | `string` | `"data-theme"` | Attribute to set on the target. |
| `storageKey` | `string` | — | Persist the choice in localStorage under this key and restore it after mount. Use a different key from ThemeToggle's `"theme"`. |
| `label` | `string` | `"Theme"` | Accessible name of the group. |

Also accepts every `RadioGroup.Root` prop.

### ThemePickerSwatch

The theme's surface as a disc holding two dots: ink and accent. Given explicit colors it
uses them; otherwise it scopes `data-theme` onto itself and reads `--background`,
`--foreground` and `--highlight`, so it follows light/dark mode too. A theme without its own
`[data-theme]` rule (usually your `:root` theme) would show the active theme's colors instead:
give it a selector too (`:root, [data-theme="default"] { … }`) or pass `swatches`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `string` | — | Theme name — used to read colors from the theme's CSS variables when `swatches` is omitted. |
| `swatches` | `string[]` | — | Explicit colors to show (any CSS color), overriding the ones read from the theme. |

Also accepts every `span` prop.

### ThemePickerItem

One theme option. Its `value` is the theme name written to the target attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | — | Theme name written to the target attribute. |
| `label` (required) | `string` | — | Theme name shown to users (the swatch's accessible name). |
| `swatches` | `string[]` | — | Colors for the swatch. Omit to read them from the theme's CSS variables. |
| `description` | `string` | — | One line under the name, shown in the `list` variant. |

Also accepts every `RadioGroup.Item` prop.

### type ThemeOption

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | — | Theme name written to the target attribute (`data-theme="paper"`). |
| `label` (required) | `string` | — | Name shown to users. |
| `swatches` | `string[]` | — | 2–3 CSS colors shown in the swatch: [surface, ink, accent]. Omit to read them from the theme's own CSS variables. |
| `description` | `string` | — | One line under the name in the `list` variant. |



---

# Theme Toggle

> Light, dark and system switch, as a sun/moon icon button or a three-way segmented control, that remembers the choice and follows the OS.

Category: Navigation · Registry item: `@portfolio-kit/theme-toggle` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/theme-toggle) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/theme-toggle.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/theme-toggle
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/theme-toggle.tsx`.

npm dependencies: `class-variance-authority`, `lucide-react`, `radix-ui`.

## Usage

```tsx
import { ThemeToggle, ThemeToggleIcon, ThemeToggleSegmented, themeToggleVariants, themeToggleSegmentedVariants, useColorMode, colorModeScript, createColorModeScript } from "@/components/portfolio/theme-toggle"
```

## Examples

### Demo

One button that flips between light and dark, remembers the choice and stays in sync with every other toggle on the page.

```tsx
import { ThemeToggle } from "@/components/portfolio/theme-toggle"
import { typography } from "@/lib/typography"

export default function ThemeToggleDemo() {
  return (
    <div className="w-full max-w-xs overflow-hidden rounded-2xl border bg-card text-card-foreground shadow-card">
      <div className="flex items-center justify-between gap-4 border-b py-2.5 pr-2.5 pl-5">
        <p className="font-heading">Noa Vale</p>
        <ThemeToggle appearance="outline" size="lg" />
      </div>
      <div className="flex flex-col gap-2 p-5">
        <p className={typography.eyebrow}>Appearance</p>
        <p className={typography.heading}>Light or dark?</p>
        <p className={typography.body}>Flip the switch — the whole page follows, and your choice is remembered.</p>
      </div>
    </div>
  )
}
```

### Segmented

A three-way light, system and dark control with a sliding thumb. “System” follows the OS setting, including later changes.

```tsx
import { ThemeToggle } from "@/components/portfolio/theme-toggle"

export default function ThemeToggleSettingsRow() {
  return (
    <div className="flex w-full max-w-sm items-center justify-between gap-6 rounded-2xl border bg-card p-5 text-card-foreground shadow-card">
      <div className="flex min-w-0 flex-col gap-1">
        <p className="text-sm font-medium">Appearance</p>
        <p className="text-sm text-pretty text-muted-foreground">Match your system, or pick a side.</p>
      </div>
      <ThemeToggle variant="segmented" />
    </div>
  )
}
```

### In a Header

The ghost icon button sits quietly beside the nav; the small segmented control fits a footer. Both share one store, so they always agree.

```tsx
import { ThemeToggle } from "@/components/portfolio/theme-toggle"
import { typography } from "@/lib/typography"

const links = [
  { label: "Work", href: "#work" },
  { label: "About", href: "#about" },
  { label: "Writing", href: "#writing" },
]

export default function ThemeToggleInHeader() {
  return (
    <div>
      <header className="flex h-16 items-center justify-between gap-6 border-b px-5 md:px-8">
        <a
          href="#top"
          className="rounded-md font-heading text-base outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
        >
          Noa Vale
        </a>
        <div className="flex items-center gap-2">
          <nav aria-label="Main" className="max-sm:hidden">
            <ul role="list" className="flex items-center gap-1">
              {links.map((link) => (
                <li key={link.href}>
                  <a
                    href={link.href}
                    className="inline-flex h-9 items-center rounded-pill px-3.5 text-sm font-medium text-muted-foreground outline-none transition-colors hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50"
                  >
                    {link.label}
                  </a>
                </li>
              ))}
            </ul>
          </nav>
          <ThemeToggle />
        </div>
      </header>
      <main className="flex flex-col gap-4 px-5 py-16 md:px-8">
        <p className={typography.eyebrow}>Appearance</p>
        <h1 className={`${typography.title} max-w-2xl`}>Flip the header toggle and the footer follows.</h1>
      </main>
      <footer className="flex items-center justify-between gap-4 border-t px-5 py-5 md:px-8">
        <p className={typography.meta}>© 2026 Noa Vale</p>
        <ThemeToggle variant="segmented" size="sm" />
      </footer>
    </div>
  )
}
```

## API Reference

### ThemeToggleIcon

Single icon button: flips between light and dark (an explicit choice, never "system").

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Button size: `sm` 32px, `default` 36px, `lg` 44px. |
| `appearance` | `"ghost" \| "outline"` | `"ghost"` | `ghost`: no border until hovered, for headers. `outline`: bordered, to sit beside other outlined buttons. |
| `mode` | `"light" \| "dark" \| "system"` | — | Controlled mode (e.g. `theme` from next-themes). When set, the toggle never touches the DOM or storage. |
| `resolvedMode` | `"light" \| "dark"` | — | Resolved mode for controlled use (e.g. `resolvedTheme`). Derived from the OS when omitted. |
| `onModeChange` | `(mode: "light" \| "dark" \| "system") => void` | — | Called with the newly chosen mode (controlled or not). |
| `storageKey` | `string` | — | localStorage key for the saved choice (uncontrolled use); defaults to `"theme"`. Every toggle sharing a key stays in sync. |
| `label` | `string` | `"Dark mode"` | Accessible name. The pressed state conveys whether dark mode is on. |
| `titles` | `Partial<Record<"light" \| "dark", string>>` | — | Tooltips: `light` while dark mode is on ("Switch to light mode"), `dark` otherwise. Translate them with `label`. |

Also accepts every `button` prop.

### ThemeToggleSegmented

Three-way light / system / dark radio group with a sliding indicator. Arrow keys move and select.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Segment size: `sm` 28px, `default` 32px, `lg` 40px. |
| `mode` | `"light" \| "dark" \| "system"` | — | Controlled mode (e.g. `theme` from next-themes). When set, the toggle never touches the DOM or storage. |
| `resolvedMode` | `"light" \| "dark"` | — | Resolved mode for controlled use (e.g. `resolvedTheme`). Derived from the OS when omitted. |
| `onModeChange` | `(mode: "light" \| "dark" \| "system") => void` | — | Called with the newly chosen mode (controlled or not). |
| `storageKey` | `string` | — | localStorage key for the saved choice (uncontrolled use); defaults to `"theme"`. Every toggle sharing a key stays in sync. |
| `label` | `string` | `"Color mode"` | Accessible name of the group. |
| `optionLabels` | `Partial<Record<"light" \| "dark" \| "system", string>>` | — | Names of the three options (accessible names and tooltips): `{ light, system, dark }`. |

Also accepts every `ToggleGroup.Root` prop.

### ThemeToggle

`variant="icon"` (default) renders ThemeToggleIcon; `variant="segmented"` renders ThemeToggleSegmented.
Both hide themselves in print.
To avoid a flash of the wrong mode on load, inline `colorModeScript` in `<head>`:
`<script dangerouslySetInnerHTML={{ __html: colorModeScript }} />` (and add `suppressHydrationWarning` to `<html>`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"icon" \| "segmented"` | — | `icon`: one button that flips light/dark. `segmented`: a light / system / dark control, for settings or footers. |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Button size: `sm` 32px, `default` 36px, `lg` 44px. |
| `appearance` | `"ghost" \| "outline"` | `"ghost"` | `ghost`: no border until hovered, for headers. `outline`: bordered, to sit beside other outlined buttons. Only with `variant="icon"`. |
| `mode` | `"light" \| "dark" \| "system"` | — | Controlled mode (e.g. `theme` from next-themes). When set, the toggle never touches the DOM or storage. |
| `resolvedMode` | `"light" \| "dark"` | — | Resolved mode for controlled use (e.g. `resolvedTheme`). Derived from the OS when omitted. |
| `onModeChange` | `(mode: "light" \| "dark" \| "system") => void` | — | Called with the newly chosen mode (controlled or not). |
| `storageKey` | `string` | — | localStorage key for the saved choice (uncontrolled use); defaults to `"theme"`. Every toggle sharing a key stays in sync. |
| `label` | `string` | — | Accessible name. The pressed state conveys whether dark mode is on. |
| `titles` | `Partial<Record<"light" \| "dark", string>>` | — | Tooltips: `light` while dark mode is on ("Switch to light mode"), `dark` otherwise. Translate them with `label`. Only with `variant="icon"`. |
| `optionLabels` | `Partial<Record<"light" \| "dark" \| "system", string>>` | — | Names of the three options (accessible names and tooltips): `{ light, system, dark }`. Only with `variant="segmented"`. |

Other props are forwarded to the root element.

## Used in templates

- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)
- [Links](https://www.parthjadhav.com/products/portfolio-kit/templates/links.md)
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md)
- [Résumé](https://www.parthjadhav.com/products/portfolio-kit/templates/resume.md)



---

# Tilt Card

> 3D card that tilts toward the pointer with a moving glare and parallax layers (`data-depth`), easing back when the pointer leaves. Off on touch and reduced motion.

Category: Effects · Registry item: `@portfolio-kit/tilt-card` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/tilt-card) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/tilt-card.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/tilt-card
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/tilt-card.tsx` and the kit items it uses: `use-composed-refs`, `use-fine-pointer`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  TiltCard,
  TiltCardLayer,
} from "@/components/portfolio/tilt-card"

<TiltCard className="p-2.5">
  <TiltCardLayer depth={18}>
    <img src="/lumen.jpg" alt="" />
  </TiltCardLayer>
  <TiltCardLayer depth={36}>
    <h3>Lumen</h3>
    <p>A design system for eleven products.</p>
  </TiltCardLayer>
</TiltCard>
```

## Examples

### Demo

A project card that tilts toward the pointer with a moving glare; the cover, badge and text float at different depths.

```tsx
import { ArrowUpRight } from "lucide-react"

import { GenerativeArt } from "@/components/portfolio/generative-art"
import { TiltCard, TiltCardLayer } from "@/components/portfolio/tilt-card"
import { typography } from "@/lib/typography"

export default function TiltCardDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-6 py-6">
      {/* Wrap the whole card: 3D layers sit in front of anything stretched over it. */}
      <a
        href="#lumen"
        aria-label="Lumen — case study"
        className="block w-full rounded-2xl outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
      >
        <TiltCard className="p-2.5">
          <TiltCardLayer depth={18} className="relative aspect-[4/3] overflow-hidden rounded-xl bg-muted">
            <GenerativeArt seed="lumen" variant="interface" />
          </TiltCardLayer>
          <span
            data-depth="56"
            className="absolute top-5 right-5 inline-flex h-7 items-center rounded-pill bg-background/85 px-3 font-mono text-xs shadow-card backdrop-blur-sm"
          >
            2025
          </span>
          <TiltCardLayer depth={36} className="flex flex-col gap-2 px-3 pt-5 pb-3">
            <p className={typography.meta}>Halcyon Labs</p>
            <div className="flex items-start justify-between gap-4">
              <h3 className={typography.heading}>Lumen</h3>
              <span aria-hidden className="inline-flex size-7 shrink-0 items-center justify-center rounded-pill border">
                <ArrowUpRight className="size-3.5" />
              </span>
            </div>
            <p className={typography.body}>
              A design system and component platform powering eleven products and 140 engineers.
            </p>
          </TiltCardLayer>
        </TiltCard>
      </a>
      <p className={typography.meta}>Move your pointer over the card</p>
    </div>
  )
}
```

### Plain

`variant="plain"` drops the card chrome so any artwork can tilt. Here a print has a caption floating 48px above it.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { TiltCard } from "@/components/portfolio/tilt-card"
import { typography } from "@/lib/typography"

export default function TiltCardPlain() {
  return (
    <div className="flex w-full max-w-xs flex-col items-center gap-6 py-6">
      <TiltCard variant="plain" maxTilt={12} className="w-full rounded-2xl">
        <div className="aspect-[4/5] overflow-hidden rounded-2xl border shadow-card">
          <GenerativeArt seed="tidewater" variant="waves" label="Tidewater, No. 3 — generative print" />
        </div>
        <p
          data-depth="48"
          className="absolute inset-x-4 bottom-4 flex items-baseline justify-between gap-3 rounded-xl bg-background/85 px-4 py-3 shadow-card backdrop-blur-sm"
        >
          <span className="text-sm font-medium">Tidewater, No. 3</span>
          <span className={typography.meta}>2025</span>
        </p>
      </TiltCard>
      <p className={typography.meta}>Move your pointer over the print</p>
    </div>
  )
}
```

### Speaker pass

A badge-like pass with a stronger tilt and lower perspective, for talks, events or an “about me” teaser.

```tsx
import { cn } from "@/lib/utils"
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { TiltCard, TiltCardLayer } from "@/components/portfolio/tilt-card"
import { typography } from "@/lib/typography"

const details = [
  { label: "Talk", value: "Tokens are an API" },
  { label: "Stage", value: "Hall B · 14:30" },
]

export default function TiltCardSpeakerPass() {
  return (
    <div className="flex w-full max-w-xs flex-col items-center gap-6 py-6">
      <TiltCard maxTilt={14} perspective={700} scale={1.04} className="flex w-full flex-col gap-6 p-5">
        <div className="flex items-center justify-between gap-4">
          <span className={typography.eyebrow}>Frontend Days ’25</span>
          <span className="inline-flex h-6 items-center rounded-pill bg-highlight px-2.5 font-mono text-[0.6875rem] font-medium text-highlight-foreground uppercase">
            Speaker
          </span>
        </div>
        <TiltCardLayer depth={40} className="flex items-center gap-4">
          <div className="size-16 shrink-0 overflow-hidden rounded-full border">
            <GenerativeArt seed="noa-vale" variant="portrait" />
          </div>
          <div className="flex min-w-0 flex-col gap-0.5">
            <h3 className={typography.heading}>Noa Vale</h3>
            <p className="text-sm text-muted-foreground">Design Engineer, Lisbon</p>
          </div>
        </TiltCardLayer>
        <TiltCardLayer depth={20}>
          <dl className="grid grid-cols-2 gap-4 border-t pt-4">
            {details.map((detail) => (
              <div key={detail.label} className="flex flex-col gap-1">
                <dt className={typography.meta}>{detail.label}</dt>
                <dd className="text-sm font-medium">{detail.value}</dd>
              </div>
            ))}
          </dl>
        </TiltCardLayer>
        <div aria-hidden className={cn(typography.meta, "flex justify-between border-t border-dashed pt-4")}>
          <span>No. 0142</span>
          <span>Lisbon · Oct 14</span>
        </div>
      </TiltCard>
      <p className={typography.meta}>Move your pointer over the pass</p>
    </div>
  )
}
```

## API Reference

### TiltCard

Children with `data-depth="24"` float 24px toward the viewer while hovered.
Don't put `overflow: hidden` on the card itself (it flattens 3D) — round and clip inner media instead.
To make the whole card a link, wrap it in one `<a>` (with the focus ring on the link): a stretched
link inside would sit behind the floating layers, and the layers' transforms would shrink its click area.
Keyboard focus doesn't tilt the card.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"card" \| "plain"` | `"card"` | `card` adds the kit card chrome (border, surface, shadow that deepens while tilted); `plain` tilts bare content. |
| `maxTilt` | `number` | `8` | Maximum rotation in degrees at the card's edges. |
| `perspective` | `number` | `1000` | Perspective distance in px. Lower is more dramatic. |
| `scale` | `number` | `1.02` | Scale while hovered. |
| `glare` | `boolean` | `true` | Show a soft light that follows the pointer across the surface. |
| `smoothing` | `number` | `0.12` | How quickly the card catches up with the pointer (0–1, per 60 Hz frame). Lower is floatier. |
| `disabled` | `boolean` | `false` | Turn the effect off (it's already off on touch screens and with reduced motion). |

Also accepts every `div` prop.

### TiltCardLayer

Convenience wrapper for a parallax layer — same as adding `data-depth` to any child.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `depth` | `number` | `24` | How far (px) the layer floats toward the viewer at full tilt. |

Also accepts every `div` prop.



---

# Timeline

> Milestones on a vertical or alternating rail with dates, icons or media, a current step, and dots that can fill as they scroll into view.

Category: About · Registry item: `@portfolio-kit/timeline` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/timeline) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/timeline.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/timeline
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/timeline.tsx` and the kit items it uses: `format`, `typography`, `use-composed-refs`, `use-in-view`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  Timeline,
  TimelineItem,
} from "@/components/portfolio/timeline"

<Timeline>
  <TimelineItem date="2019-03" heading="Joined Paperplane Studio" description="Four years of fintech and climate products." />
  <TimelineItem date="2025-10-14" heading="Launched Lumen 2.0" active />
</Timeline>
```

## Examples

### Demo

Milestones on a vertical rail with icon badges. The current step gets a highlighted halo and `aria-current`.

```tsx
import { Briefcase, GraduationCap, Rocket, Star } from "lucide-react"

import { Timeline, TimelineItem } from "@/components/portfolio/timeline"

export default function TimelineDemo() {
  return (
    <Timeline className="w-full max-w-lg">
      <TimelineItem
        date="2016-09"
        heading="Graduated in Interaction Design"
        description="Thesis on perceptual colour spaces for data visualisation."
        icon={<GraduationCap />}
      />
      <TimelineItem
        date="2019-03"
        heading="Joined Paperplane Studio"
        description="Four years shipping fintech and climate products, from first sketch to production."
        icon={<Briefcase />}
      />
      <TimelineItem
        date="2023-06"
        heading="Paperplane library hits 4k stars"
        description="A tiny animation library that started as a weekend experiment."
        icon={<Star />}
      />
      <TimelineItem
        date="2025-10-14"
        heading="Launched Lumen 2.0"
        description="The design system now powers eleven products and 140 engineers."
        icon={<Rocket />}
        active
      />
    </Timeline>
  )
}
```

### Alternating

Items zig-zag either side of a centre line on desktop and collapse to a single rail on phones.

```tsx
import { Timeline, TimelineItem } from "@/components/portfolio/timeline"

export default function TimelineAlternating() {
  return (
    <Timeline variant="alternating" className="mx-auto w-full max-w-4xl py-6">
      <TimelineItem date="2014" heading="First line of CSS" description="A fan site for a band nobody remembers. The marquee tag was involved." />
      <TimelineItem date="2016-09" heading="Design school" description="Graduated in Interaction Design with a thesis on colour for data visualisation." />
      <TimelineItem date="2019-03" heading="Studio years" description="Joined Paperplane Studio and shipped a dozen products for fintech and climate clients." />
      <TimelineItem date="2022-03" heading="Going deep on systems" description="Now leading the Lumen design system at Halcyon Labs." active />
    </Timeline>
  )
}
```

### With Media

Attach a screenshot or artwork to any milestone, for a project changelog or launch history.

```tsx
import { GenerativeArt } from "@/components/portfolio/generative-art"
import { Media } from "@/components/portfolio/media"
import { Timeline, TimelineItem } from "@/components/portfolio/timeline"

export default function TimelineWithMedia() {
  return (
    <Timeline className="w-full max-w-lg">
      <TimelineItem
        date="2024-04"
        heading="Fieldnote brand launch"
        description="Identity, type system and marketing site shipped in six weeks."
        media={
          <Media ratio="video" bordered caption="The launch site hero">
            <GenerativeArt seed="fieldnote" variant="interface" label="Fieldnote launch site hero" />
          </Media>
        }
      />
      <TimelineItem
        date="2025-02"
        heading="Tidewater dashboard goes live"
        description="Real-time monitoring for 40 coastal wind farms."
        media={
          <Media ratio="video" bordered>
            <GenerativeArt seed="tidewater" variant="interface" label="Tidewater dashboard" />
          </Media>
        }
        active
      />
    </Timeline>
  )
}
```

### Fill on Scroll

With `fillOnView`, each dot fills with the highlight as its milestone scrolls into view. Scroll the preview to see it.

```tsx
import { cn } from "@/lib/utils"
import { Timeline, TimelineItem } from "@/components/portfolio/timeline"
import { typography } from "@/lib/typography"

const milestones = [
  { date: "2014", heading: "Wrote my first line of CSS", description: "A fan site, a marquee tag and a lifelong habit." },
  { date: "2016-09", heading: "Graduated in Interaction Design", description: "Thesis on perceptual colour spaces." },
  { date: "2019-03", heading: "Joined Paperplane Studio", description: "Shipping products from first sketch to production." },
  { date: "2022-03", heading: "Joined Halcyon Labs", description: "Leading the Lumen design system." },
  { date: "2025-10", heading: "Launched Lumen 2.0", description: "Eleven products, one visual language." },
]

export default function TimelineFillOnScroll() {
  return (
    <div className="mx-auto w-full max-w-lg pt-6">
      <p className={cn(typography.meta, "mb-16")}>Scroll ↓</p>
      <Timeline fillOnView>
        {milestones.map((milestone) => (
          <TimelineItem key={milestone.heading} {...milestone} className="pb-28" />
        ))}
      </Timeline>
    </div>
  )
}
```

## API Reference

### Timeline

An ordered list of milestones on a rail. Put `TimelineItem`s inside, oldest or newest first.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"vertical" \| "alternating" \| null` | `"vertical"` | `vertical`: one rail on the leading edge. `alternating`: items zig-zag around a center line from `md` up. |
| `fillOnView` | `boolean` | `false` | Fill each dot with the highlight color as its item scrolls into view. |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading element for each milestone. Pick the level below the section's heading. |

Also accepts every `ol` prop.

### TimelineItem

One milestone: date, heading, description, and optional icon or media. Extra children render after the description.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `React.ReactNode` | — | What happened. Rendered as the timeline's `headingLevel` (`<h3>` by default). Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `date` | `string` | — | "2019", "2019-04" → "Apr 2019", "2019-04-12" → "Apr 12, 2019", or free text. |
| `description` | `React.ReactNode` | — | A sentence or two of detail. |
| `icon` | `React.ReactNode` | — | Icon in a round badge on the rail, replacing the dot. |
| `media` | `React.ReactNode` | — | Image, video or artwork under the description. |
| `active` | `boolean` | `false` | The current step: highlighted dot with a halo and `aria-current`. |
| `locale` | `string` | `"en-US"` | Locale used to format month and day dates. |

Also accepts every `li` prop.



---

# Tool Grid

> A /uses page: tools grouped by category, with logos or monogram tiles, short notes, favorites and optional links.

Category: About · Registry item: `@portfolio-kit/tool-grid` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/tool-grid) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/tool-grid.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/tool-grid
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/tool-grid.tsx` and the kit items it uses: `typography`.

npm dependencies: `lucide-react`.

## Usage

```tsx
import {
  ToolCategory,
  ToolGrid,
  ToolItem,
} from "@/components/portfolio/tool-grid"

<ToolGrid>
  <ToolCategory heading="Design" description="Where ideas get shape.">
    <ToolItem name="Figma" description="Wireframes, prototypes and the design system." href="https://example.com" favorite />
    <ToolItem name="Sketchbook" description="Dot-grid notebooks for thinking." />
  </ToolCategory>
  <ToolCategory heading="Development">
    <ToolItem name="Quill Editor" meta="Free · macOS" description="A fast, minimal code editor." />
  </ToolCategory>
</ToolGrid>
```

## Examples

### Demo

Tools grouped by category with logos or monogram tiles, short notes, favorites and links.

```tsx
import { BrandIcon } from "@/components/portfolio/brand-icons"
import { ToolCategory, ToolGrid, ToolItem } from "@/components/portfolio/tool-grid"

export default function ToolGridDemo() {
  return (
    <ToolGrid className="mx-auto w-full max-w-5xl py-6">
      <ToolCategory heading="Design" description="Where ideas get shape before they get code.">
        <ToolItem
          name="Figma"
          icon={<BrandIcon name="figma" />}
          description="Wireframes, prototypes and the design system source of truth."
          href="https://example.com/figma"
          favorite
        />
        <ToolItem name="Colorway" meta="Paid · macOS" description="Builds accessible palettes and checks contrast pairs." href="https://example.com/colorway" />
        <ToolItem name="Sketchbook" description="Dot-grid notebooks and a 0.5mm fineliner for thinking." />
      </ToolCategory>
      <ToolCategory heading="Development" description="A small, boring, reliable stack.">
        <ToolItem name="Quill Editor" description="A fast, minimal code editor with vim bindings." href="https://example.com/quill" favorite />
        <ToolItem
          name="GitHub"
          icon={<BrandIcon name="github" />}
          description="Code, issues and the occasional heated discussion."
          href="https://example.com/github"
        />
        <ToolItem name="Tern Terminal" description="GPU-accelerated terminal with sensible defaults." href="https://example.com/tern" />
      </ToolCategory>
    </ToolGrid>
  )
}
```

### Hardware

A single category. Lucide icons stand in for gear without a logo, and `meta` adds a short detail line.

```tsx
import { Headphones, Keyboard, Laptop, Monitor } from "lucide-react"

import { ToolCategory, ToolGrid, ToolItem } from "@/components/portfolio/tool-grid"

export default function ToolGridHardware() {
  return (
    <ToolGrid className="mx-auto w-full max-w-5xl py-6">
      <ToolCategory heading="Desk" description="Hardware I'd happily buy again.">
        <ToolItem name="14-inch laptop" icon={<Laptop />} meta="Bought 2024" description="Silent, cool and fast enough for everything." />
        <ToolItem name="27-inch 5K display" icon={<Monitor />} description="Sharp text makes long days easier." favorite />
        <ToolItem name="Split keyboard" icon={<Keyboard />} meta="Custom build" description="Low-profile switches, tented at 10°." />
        <ToolItem name="Closed-back headphones" icon={<Headphones />} description="Focus mode for open-plan days." />
      </ToolCategory>
    </ToolGrid>
  )
}
```

### Uses Page

A full /uses section: a page heading, then categories whose titles stay beside their tool cards on desktop.

```tsx
import { BrandIcon } from "@/components/portfolio/brand-icons"
import {
  Section,
  SectionContent,
  SectionDescription,
  SectionEyebrow,
  SectionHeader,
  SectionTitle,
} from "@/components/portfolio/section"
import { ToolCategory, ToolGrid, ToolItem } from "@/components/portfolio/tool-grid"

export default function ToolGridUsesPage() {
  return (
    <Section spacing="sm">
      <SectionHeader>
        <SectionEyebrow>/uses</SectionEyebrow>
        <SectionTitle>Tools of the trade</SectionTitle>
        <SectionDescription>The software and hardware I reach for every day. Nothing here is sponsored.</SectionDescription>
      </SectionHeader>
      <SectionContent>
        <ToolGrid>
          <ToolCategory heading="Apps" description="Small tools that stay out of the way.">
            <ToolItem name="Notebook" description="Plain-text notes synced everywhere." href="https://example.com/notebook" favorite />
            <ToolItem name="Raycaster" description="Launcher, clipboard history and window management." href="https://example.com/raycaster" />
            <ToolItem name="Pixel Picker" description="A colour picker that speaks oklch." />
            <ToolItem
              name="Spotify"
              icon={<BrandIcon name="spotify" />}
              description="Ambient playlists on repeat while I work."
              href="https://example.com/spotify"
            />
          </ToolCategory>
          <ToolCategory heading="Publishing" description="How this site gets made.">
            <ToolItem name="Portfolio Kit" description="The components you're looking at right now." href="https://example.com/kit" favorite />
            <ToolItem name="Mailbox" meta="Free tier" description="A tiny newsletter every other month." href="https://example.com/newsletter" />
          </ToolCategory>
        </ToolGrid>
      </SectionContent>
    </Section>
  )
}
```

## API Reference

### ToolGrid

Stack of `ToolCategory` sections.

Also accepts every `div` prop.

### ToolCategory

A category: its heading stays beside the cards (sticky) on large screens and sits above them on small ones.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `React.ReactNode` | — | Category name, e.g. "Design", with the item count beside it. Required (or the deprecated `title`). |
| `title` | `React.ReactNode` | — | Deprecated alias of `heading`. |
| `headingLevel` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the category name. Tool names inside are one level below (`h3` → `h4`). Use `h2` when the categories are the page's main sections. |
| `description` | `React.ReactNode` | — | One line about the category. |
| `listClassName` | `string` | — | Class for the grid that wraps the items (one column, two from `sm`). |

Also accepts every `section` prop.

### ToolItem

One tool as a card: icon tile, name, meta and a short note.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Tool name. Rendered as a heading one level below the category's (an `<h4>` by default). |
| `description` | `React.ReactNode` | — | What you use it for, in a sentence. |
| `icon` | `React.ReactNode` | — | Logo or icon, shown in a tile. Defaults to a monogram of the first letter of `name`. Use `currentColor` SVGs (such as `BrandIcon`) so logos follow light and dark mode; a dark `<img>` logo disappears on a dark tile. |
| `href` | `string` | — | Makes the whole card a link. External links open in a new tab and say so to screen readers. |
| `newTabLabel` | `string` | `"(opens in a new tab)"` | Screen-reader text added when `href` opens in a new tab. Translate it here. |
| `favorite` | `boolean` | — | Mark as a favorite with a small star after the name. |
| `favoriteLabel` | `string` | `"Favorite"` | Tooltip and screen-reader name of the favorite star. |
| `meta` | `React.ReactNode` | — | Short meta under the name, e.g. "Paid · macOS". |

Also accepts every `li` prop.

## Used in templates

- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)



---

# Type Specimen

> A typeface showcase for case studies: a big “Aa”, the font’s name and foundry, its weights, the character set and a size ladder, all set in the project’s font.

Category: Work · Registry item: `@portfolio-kit/type-specimen` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/type-specimen) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/type-specimen.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/type-specimen
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/type-specimen.tsx`.

## Usage

```tsx
import {
  TypeSpecimen,
  TypeSpecimenCharset,
  TypeSpecimenGlyph,
  TypeSpecimenHeader,
  TypeSpecimenScale,
  TypeSpecimenWeights,
} from "@/components/portfolio/type-specimen"

<TypeSpecimen fontFamily="'Tidewater Sans', sans-serif">
  <TypeSpecimenGlyph label="Headline" detail="Aa" />
  <TypeSpecimenHeader name="Tidewater Sans" note="Custom cut by North Foundry">
    <TypeSpecimenWeights />
  </TypeSpecimenHeader>
  <TypeSpecimenCharset />
  <TypeSpecimenScale />
</TypeSpecimen>
```

## Examples

### Demo

A typeface at full size: the big glyph with its metrics, name and license, weights, character set and the size ladder, set in your theme’s heading font.

```tsx
import {
  TypeSpecimen,
  TypeSpecimenCharset,
  TypeSpecimenGlyph,
  TypeSpecimenHeader,
  TypeSpecimenScale,
  TypeSpecimenWeights,
} from "@/components/portfolio/type-specimen"

export default function TypeSpecimenDemo() {
  return (
    <TypeSpecimen className="mx-auto w-full max-w-4xl">
      <div className="grid gap-6 md:grid-cols-[minmax(0,2fr)_minmax(0,3fr)] md:items-end">
        <TypeSpecimenGlyph label="Headline" detail="Aa" />
        <TypeSpecimenHeader name="Tidewater Sans" note="Custom cut by North Foundry · Licensed for web & app">
          <TypeSpecimenWeights className="mt-4 sm:grid-cols-2" />
        </TypeSpecimenHeader>
      </div>
      <TypeSpecimenCharset />
      <TypeSpecimenScale labels={{ 72: "Display", 48: "Title", 32: "Heading", 20: "Lead", 16: "Body" }} />
    </TypeSpecimen>
  )
}
```

### Secondary face

Pass any `fontFamily`: here the theme’s code font as the supporting face for data and labels, with a shorter ladder and a figures-only charset.

```tsx
import {
  TypeSpecimen,
  TypeSpecimenCharset,
  TypeSpecimenHeader,
  TypeSpecimenScale,
  TypeSpecimenWeights,
} from "@/components/portfolio/type-specimen"

export default function TypeSpecimenSecondaryFace() {
  return (
    <TypeSpecimen fontFamily="var(--font-code, ui-monospace, monospace)" className="mx-auto w-full max-w-3xl gap-8">
      <TypeSpecimenHeader name="Tidewater Mono" note="For readings, timestamps and IDs · Tabular figures on">
        <TypeSpecimenWeights weights={[400, 700]} sample="0.42" className="mt-4 sm:grid-cols-2" />
      </TypeSpecimenHeader>
      <TypeSpecimenCharset characters="0123456789.%" />
      <TypeSpecimenScale sizes={[32, 16, 12]} sample="T-04 · 12.8 MW · 03:14" labels={{ 32: "Readout", 16: "Table", 12: "Label" }} />
    </TypeSpecimen>
  )
}
```

### In a case study

The typography chapter of a case study, set in the project’s own typeface (here, your theme’s heading font).

```tsx
import {
  CaseStudyProse,
  CaseStudySection,
  CaseStudySectionContent,
  CaseStudySectionLabel,
} from "@/components/portfolio/case-study-section"
import { Container } from "@/components/portfolio/section"
import {
  TypeSpecimen,
  TypeSpecimenCharset,
  TypeSpecimenGlyph,
  TypeSpecimenHeader,
  TypeSpecimenScale,
  TypeSpecimenWeights,
} from "@/components/portfolio/type-specimen"

export default function TypeSpecimenInACaseStudy() {
  return (
    <Container className="py-10 md:py-16">
      <CaseStudySection aria-labelledby="type">
        <CaseStudySectionLabel index={4} id="type">
          Typography
        </CaseStudySectionLabel>
        <CaseStudySectionContent className="flex flex-col gap-10">
          <CaseStudyProse>
            <p>
              One family does all the work. Big, tight headlines give the dashboard a voice; the same face at 16px keeps
              dense tables readable at three in the morning.
            </p>
          </CaseStudyProse>
          <TypeSpecimen>
            <div className="grid gap-6 md:grid-cols-[minmax(0,2fr)_minmax(0,3fr)] md:items-end">
              <TypeSpecimenGlyph label="Headline" detail="Aa" />
              <TypeSpecimenHeader name="Tidewater Sans" note="Custom cut by North Foundry · Licensed for web & app">
                <TypeSpecimenWeights className="mt-4 sm:grid-cols-2" />
              </TypeSpecimenHeader>
            </div>
            <TypeSpecimenCharset />
            <TypeSpecimenScale labels={{ 72: "Display", 48: "Title", 32: "Heading", 20: "Lead", 16: "Body" }} />
          </TypeSpecimen>
        </CaseStudySectionContent>
      </CaseStudySection>
    </Container>
  )
}
```

## API Reference

### TypeSpecimen

The specimen. Every part inside is set in `fontFamily`. A typical layout: `<TypeSpecimenGlyph>` beside
`<TypeSpecimenHeader>` + `<TypeSpecimenWeights>`, then `<TypeSpecimenCharset>` and `<TypeSpecimenScale>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fontFamily` | `string` | — | CSS `font-family` to show, e.g. `"'Fraunces', serif"`. Load the font yourself. Defaults to the theme's heading font. |

Also accepts every `div` prop.

### TypeSpecimenGlyph

A large glyph card ("Aa" by default) with baseline, x-height and cap-height guides taken from the font.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `React.ReactNode` | — | Small label in the top-left corner, e.g. "Regular 400". |
| `detail` | `React.ReactNode` | — | Small label in the bottom-right corner, e.g. "U+0041". |

Also accepts every `figure` prop.

### TypeSpecimenHeader

Name of the typeface (in the typeface) plus a foundry / license line. Children go underneath.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | The typeface's name, set in itself. |
| `note` | `React.ReactNode` | — | Foundry, designer or license note, e.g. "Undercase Type · SIL Open Font License". |
| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level for `name`. |

Also accepts every `div` prop.

### TypeSpecimenWeights

A row of the same sample at each weight, labelled "Light 300", "Bold 700"…

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `weights` | `number[]` | `[300, 400, 600, 800]` | Weights to show (numbers 100–900). The font must include them, or the browser will fake bold. |
| `sample` | `string` | `"Aa"` | What each weight shows. |
| `weightNames` | `Partial<Record<number, string>>` | — | Names shown before each weight number, e.g. `{ 400: "Normal" }` or a translation. Unnamed weights show "Weight". |

Also accepts every `ul` prop.

### TypeSpecimenCharset

The character set in an even grid, one glyph per cell. Rows are always complete: up to 12
characters sit on one row; longer sets use 6 columns (12 from `sm`) and pad the last row with
blank cells.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `characters` | `string` | `"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789&@?!%€$#*+"` | Characters to lay out, one per cell. Defaults to A–Z, a–z, 0–9 and `&@?!%€$#*+`. |
| `label` | `string` | `"Character set"` | What screen readers hear before the characters (the grid itself is hidden from them). Translate it here. |

Also accepts every `div` prop.

### TypeSpecimenScale

A size ladder: the same line at each size, with its px/rem and an optional role label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sizes` | `number[]` | `[72, 48, 32, 20, 16]` | Sizes in px, largest first. |
| `sample` | `string` | `"Calm interfaces for loud data"` | The line shown at every size. |
| `labels` | `Record<number, string>` | — | Label per size, e.g. `{ 72: "Display", 16: "Body" }`. |

Also accepts every `ol` prop.

## Used in templates

- [Case Study](https://www.parthjadhav.com/products/portfolio-kit/templates/case-study.md)



---

# Version Label

> Small-print footer line with version, last-updated date, copyright and edition number, plus a colophon that credits typefaces and tools.

Category: Utilities · Registry item: `@portfolio-kit/version-label` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/version-label) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/version-label.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/version-label
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/version-label.tsx` and the kit items it uses: `format`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import {
  Colophon,
  ColophonItem,
  VersionLabel,
} from "@/components/portfolio/version-label"

<Colophon>
  <ColophonItem label="Version">
    <VersionLabel version="4.2" updated="2025-10-14" />
  </ColophonItem>
  <ColophonItem label="Type">Grotesk Neue, Plex Mono</ColophonItem>
</Colophon>
```

## Examples

### Demo

The small signature line in a footer: version, a last-updated date rendered as a real `<time>`, and a highlight dot.

```tsx
import { VersionLabel } from "@/components/portfolio/version-label"

export default function VersionLabelDemo() {
  return (
    <footer className="flex w-full max-w-md flex-col gap-6">
      <div className="flex flex-col gap-1">
        <p className="font-heading text-2xl">Noa Vale</p>
        <p className="text-sm text-muted-foreground">Design engineer in Lisbon. Booking projects from March.</p>
      </div>
      <div className="flex flex-col items-start gap-3 border-t pt-5">
        <VersionLabel variant="pill" version="4.2" dot updated="2025-10-14" />
        <VersionLabel copyright="2025 Noa Vale" edition={19} />
      </div>
    </footer>
  )
}
```

### Variations

Mix copyright, version, a Roman-numeral edition, a custom date label and your own trailing parts — separators are added for you.

```tsx
import { VersionLabel } from "@/components/portfolio/version-label"

export default function VersionLabelVariations() {
  return (
    <div className="flex flex-col items-start gap-5">
      <VersionLabel copyright="2025 Noa Vale" edition={19} />
      <VersionLabel version="Beta 3" dot updated="2025-06-01" updatedLabel="Shipped" />
      <VersionLabel variant="pill" dot version="12.0.1" updated="2025-10-14" />
      <VersionLabel copyright={2025} version="4.2">
        <span>Made in Lisbon</span>
      </VersionLabel>
    </div>
  )
}
```

### Colophon

Credit your typefaces, tools and hosting with `Colophon` — dotted leaders like a printed book, or a grid or inline row.

```tsx
import { Colophon, ColophonItem } from "@/components/portfolio/version-label"
import { typography } from "@/lib/typography"

export default function VersionLabelColophon() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-10">
      <div>
        <p className={typography.eyebrow}>Colophon</p>
        <Colophon
          className="mt-4"
          items={[
            { label: "Typeface", value: "Geist & Geist Mono" },
            { label: "Built with", value: "React, Tailwind CSS" },
            { label: "Hosted on", value: <a href="https://example.com">Example Cloud</a> },
            { label: "Set in", value: "Lisbon, Portugal" },
          ]}
        />
      </div>
      <Colophon variant="inline">
        <ColophonItem label="Type">Geist</ColophonItem>
        <ColophonItem label="Code">React</ColophonItem>
        <ColophonItem label="Host">Example Cloud</ColophonItem>
      </Colophon>
    </div>
  )
}
```

### In a Footer

Inside a Site Footer: sign-off and colophon on top, the edition and version labels along the small-print row.

```tsx
import {
  SiteFooter,
  SiteFooterBottom,
  SiteFooterBrand,
  SiteFooterGrid,
} from "@/components/portfolio/site-footer"
import { Colophon, VersionLabel } from "@/components/portfolio/version-label"
import { typography } from "@/lib/typography"

const colophon = [
  { label: "Typeface", value: "Geist & Geist Mono" },
  { label: "Built with", value: "React, Tailwind CSS" },
  { label: "Hosted on", value: <a href="https://example.com">Example Cloud</a> },
]

export default function VersionLabelInAFooter() {
  return (
    <SiteFooter>
      <SiteFooterGrid>
        <SiteFooterBrand>
          <p className="font-heading text-3xl">Noa Vale</p>
          <p className="text-sm text-muted-foreground">
            I design and build calm, fast interfaces for ambitious product teams.
          </p>
        </SiteFooterBrand>
        <div className="col-span-2 w-full md:max-w-xs md:justify-self-end">
          <p className={typography.eyebrow}>Colophon</p>
          <Colophon className="mt-4" items={colophon} />
        </div>
      </SiteFooterGrid>
      <SiteFooterBottom>
        <VersionLabel copyright="2025 Noa Vale" edition={19} />
        <VersionLabel version="4.2" dot updated="2025-10-14" />
      </SiteFooterBottom>
    </SiteFooter>
  )
}
```

## API Reference

### VersionLabelDate

A `<time>` element formatted as "Oct 2025" (UTC, so it never shifts a month across time zones).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `date` (required) | `Date \| string \| number` | — | A `Date`, ISO string (`"2025-10-14"`) or timestamp. Unparseable input is shown as text. |
| `format` | `Intl.DateTimeFormatOptions` | — | `Intl.DateTimeFormat` options merged over the default "Oct 2025" (`{ month: "long" }` → "October 2025"). Options with `dateStyle` replace the default instead. |
| `locale` | `string` | `"en-US"` | BCP 47 locale for the date. |

Also accepts every `time` prop.

### VersionLabel

One line of small print. Parts render in a fixed order — copyright, version, edition, updated,
then your `children` — with an em dash between each (silent for screen readers). The line wraps
between parts on narrow screens. Pass `updatedLabel` and `editionLabel` to translate the labels.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"plain" \| "pill"` | `"plain"` | `plain`: a line of small print. `pill`: the same line in a bordered pill, for a footer corner. |
| `version` | `string \| number` | — | "4.2" → "v4.2". Strings starting with a letter are shown as-is. |
| `updated` | `Date \| string \| number` | — | Last update. Rendered as `<time>` — "Last updated Oct 2025". |
| `updatedLabel` | `React.ReactNode` | `"Last updated"` | Text before the date. |
| `edition` | `number` | — | Edition number, rendered in Roman numerals: 19 → "Edition XIX". |
| `editionLabel` | `React.ReactNode` | `"Edition"` | Text before the edition number. |
| `copyright` | `boolean \| number \| string` | — | A number or string is used as the year/holder, e.g. `"2025 Noa Vale"`. `true` → "© {current year}", read when the page renders: on a statically built page that's the build year, so pass the year (or rebuild in January) if that matters. |
| `dot` | `boolean` | `false` | Leading highlight dot before the version. |
| `locale` | `string` | — | BCP 47 locale for the `updated` date. |

Also accepts every `p` prop.

### Colophon

A small definition list crediting typefaces, tools and hosting.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"leader" \| "grid" \| "inline"` | `"leader"` | `leader`: label and value joined by a dotted rule. `grid`: each label above its value, in columns. `inline`: one flowing line, for tight footers. |
| `items` | `{ label: React.ReactNode; value: React.ReactNode }[]` | — | Shortcut: `[{ label: "Typeface", value: "Geist" }, …]`. |

Also accepts every `dl` prop.

### ColophonItem

One label/value pair of a `Colophon`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `React.ReactNode` | — | The term (`<dt>`), e.g. "Typeface". `children` is the value (`<dd>`); links inside are styled. |

Also accepts every `div` prop.

## Used in templates

- [Developer](https://www.parthjadhav.com/products/portfolio-kit/templates/developer.md)
- [Minimal](https://www.parthjadhav.com/products/portfolio-kit/templates/minimal.md)
- [Uses](https://www.parthjadhav.com/products/portfolio-kit/templates/uses.md)



---

# View Toggle

> Segmented grid / list / index switch with a sliding indicator, for choosing how a work section is laid out.

Category: Work · Registry item: `@portfolio-kit/view-toggle` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/view-toggle) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/view-toggle.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/view-toggle
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/view-toggle.tsx`.

npm dependencies: `class-variance-authority`, `lucide-react`, `radix-ui`.

## Usage

```tsx
import {
  ViewToggle,
  ViewToggleItem,
} from "@/components/portfolio/view-toggle"

<ViewToggle aria-label="Layout" defaultValue="grid">
  <ViewToggleItem value="grid" />
  <ViewToggleItem value="list" />
</ViewToggle>
```

## Examples

### Demo

A grid / list / index switch with a sliding indicator in the toolbar of a work section: pick a view and the projects below re-lay themselves out.

```tsx
import * as React from "react"

import { GenerativeArt } from "@/components/portfolio/generative-art"
import { ViewToggle } from "@/components/portfolio/view-toggle"
import { typography } from "@/lib/typography"

// Title links: highlight on hover, a visible ring for keyboard focus.
const link = "rounded-sm outline-none transition-colors duration-200 hover:text-highlight-ink focus-visible:ring-[3px] focus-visible:ring-ring/50"

const projects = [
  { slug: "lumen", title: "Lumen", client: "Halcyon Labs", year: 2025, art: "interface", hue: 250 },
  { slug: "tidewater", title: "Tidewater", client: "Tidewater Energy", year: 2025, art: "interface", hue: 195 },
  { slug: "fieldnote", title: "Fieldnote", client: "Fieldnote Inc.", year: 2024, art: "bauhaus", hue: 132 },
] as const

export default function ViewToggleDemo() {
  const [view, setView] = React.useState("grid")

  return (
    <div className="flex w-full max-w-md flex-col gap-5">
      <div className="flex items-end justify-between gap-6 border-b pb-5">
        <div className="flex flex-col gap-2">
          <p className={typography.eyebrow}>Selected work</p>
          <p className="font-heading text-2xl">Three projects</p>
        </div>
        <ViewToggle value={view} onValueChange={setView} aria-label="Layout" />
      </div>
      {view === "grid" && (
        <ul role="list" className="grid grid-cols-3 gap-3">
          {projects.map((project) => (
            <li key={project.slug} className="flex flex-col gap-2">
              <div className="aspect-[4/3] overflow-hidden rounded-lg border">
                <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
              </div>
              <a href={`#${project.slug}`} className={`py-0.5 text-sm font-medium ${link}`}>
                {project.title}
              </a>
            </li>
          ))}
        </ul>
      )}
      {view === "list" && (
        <ul role="list" className="flex flex-col">
          {projects.map((project) => (
            <li key={project.slug} className="flex items-center gap-3 border-b py-3">
              <div className="size-10 shrink-0 overflow-hidden rounded-md border">
                <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} grain={false} />
              </div>
              <a href={`#${project.slug}`} className={`text-sm font-medium ${link}`}>
                {project.title}
              </a>
              <span className="ml-auto font-mono text-xs text-muted-foreground">{project.client}</span>
            </li>
          ))}
        </ul>
      )}
      {view === "index" && (
        <ul role="list" className="flex flex-col">
          {projects.map((project) => (
            <li key={project.slug} className="flex items-baseline justify-between gap-4 border-b py-3">
              <a href={`#${project.slug}`} className={`font-heading text-xl ${link}`}>
                {project.title}
              </a>
              <span className={typography.meta}>{project.year}</span>
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}
```

### With Labels

Visible text labels make the choice explicit; `size="sm"` fits dense toolbars.

```tsx
import { ViewToggle } from "@/components/portfolio/view-toggle"

export default function ViewToggleWithLabels() {
  return (
    <div className="flex flex-col items-center gap-6">
      <ViewToggle labels="visible" aria-label="Layout" />
      <ViewToggle labels="visible" size="sm" defaultValue="index" aria-label="Layout (small)" />
    </div>
  )
}
```

### Custom Views

Compose your own `ViewToggleItem`s with any value, label and lucide icon.

```tsx
import { Columns2, GalleryHorizontal, LayoutGrid } from "lucide-react"

import { ViewToggle, ViewToggleItem } from "@/components/portfolio/view-toggle"

export default function ViewToggleCustomViews() {
  return (
    <div className="flex w-full max-w-md flex-wrap items-center justify-between gap-4 border-b pb-4">
      <div>
        <p className="font-heading text-lg">Coastlines</p>
        <p className="font-mono text-xs text-muted-foreground">24 photographs</p>
      </div>
      <ViewToggle labels="visible" defaultValue="split" aria-label="Gallery layout">
        <ViewToggleItem value="grid" label="Grid" icon={<LayoutGrid />} />
        <ViewToggleItem value="split" label="Split" icon={<Columns2 />} />
        <ViewToggleItem value="strip" label="Strip" icon={<GalleryHorizontal />} />
      </ViewToggle>
    </div>
  )
}
```

### Switching Layouts

Control the toggle and render the same projects as a card grid or a typographic index.

```tsx
import * as React from "react"

import { GenerativeArt } from "@/components/portfolio/generative-art"
import {
  ProjectCard,
  ProjectCardContent,
  ProjectCardMedia,
  ProjectCardMeta,
  ProjectCardTitle,
} from "@/components/portfolio/project-card"
import { ProjectGrid, ProjectGridItem } from "@/components/portfolio/project-grid"
import { ProjectList, ProjectListItem } from "@/components/portfolio/project-list"
import { ViewToggle, ViewToggleItem } from "@/components/portfolio/view-toggle"
import { typography } from "@/lib/typography"

const projects = [
  { slug: "lumen", title: "Lumen", client: "Halcyon Labs", year: 2025, art: "interface", hue: 250 },
  { slug: "tidewater", title: "Tidewater", client: "Tidewater Energy", year: 2025, art: "interface", hue: 195 },
  { slug: "fieldnote", title: "Fieldnote", client: "Fieldnote Inc.", year: 2024, art: "bauhaus", hue: 132 },
] as const

export default function ViewToggleSwitchingLayouts() {
  const [view, setView] = React.useState("grid")

  return (
    <div className="mx-auto flex max-w-5xl flex-col gap-8">
      <div className="flex items-center justify-between gap-4">
        <p className={typography.eyebrow}>{projects.length} projects</p>
        <ViewToggle value={view} onValueChange={setView} aria-label="Layout">
          <ViewToggleItem value="grid" />
          <ViewToggleItem value="list" />
        </ViewToggle>
      </div>
      {view === "grid" ? (
        <ProjectGrid>
          {projects.map((project) => (
            <ProjectGridItem key={project.slug}>
              <ProjectCard href={`#${project.slug}`}>
                <ProjectCardMedia>
                  <GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />
                </ProjectCardMedia>
                <ProjectCardContent>
                  <ProjectCardMeta>
                    <span>{project.year}</span>
                    <span>{project.client}</span>
                  </ProjectCardMeta>
                  <ProjectCardTitle>{project.title}</ProjectCardTitle>
                </ProjectCardContent>
              </ProjectCard>
            </ProjectGridItem>
          ))}
        </ProjectGrid>
      ) : (
        <ProjectList>
          {projects.map((project) => (
            <ProjectListItem
              key={project.slug}
              href={`#${project.slug}`}
              heading={project.title}
              client={project.client}
              year={project.year}
              preview={<GenerativeArt seed={project.slug} variant={project.art} hue={project.hue} />}
            />
          ))}
        </ProjectList>
      )}
    </div>
  )
}
```

## API Reference

### ViewToggle

Renders grid / list / index by default; pass `ViewToggleItem`s to choose your own views.
A radio group: one view is always selected (clicking the active one does nothing) and the
arrow keys move the selection.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "sm"` | `"default"` | `default` (44px tall) for page toolbars, `sm` (36px) beside filter chips or in dense headers. |
| `value` | `string` | — | The selected view (controlled). Pair with `onValueChange`. |
| `defaultValue` | `string` | `"grid"` | The initially selected view (uncontrolled). Defaults to `"grid"`; set it when your items don't include `grid`. |
| `onValueChange` | `(value: string) => void` | — | Called with the newly selected view. Never called with an empty value. |
| `labels` | `"sr-only" \| "visible"` | `"sr-only"` | Show text labels next to the icons, or keep them for screen readers only. |

Also accepts every `ToggleGroup.Root` prop.

### ViewToggleItem

One view. `value` is what `onValueChange` receives; `grid`, `list` and `index` come with a label and icon.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | Defaults to the built-in label for `grid`, `list` and `index`. |
| `icon` | `React.ReactNode` | — | Defaults to the built-in icon for `grid`, `list` and `index`. |

Also accepts every `ToggleGroup.Item` prop.



---

# Word Rotate

> Cycles words inside a headline with a slide-and-blur swap, in a slot as wide as the widest word so the line never reflows. Screen readers get one static sentence.

Category: Hero · Registry item: `@portfolio-kit/word-rotate` · [Live docs](https://www.parthjadhav.com/products/portfolio-kit/components/word-rotate) · [Registry JSON](https://www.parthjadhav.com/products/portfolio-kit/r/word-rotate.json)

## Installation

```bash
npx shadcn@latest add @portfolio-kit/word-rotate
```

Requires the `@portfolio-kit` registry in `components.json` — see [Installation](https://www.parthjadhav.com/products/portfolio-kit/docs/installation.md).

Adds `components/portfolio/word-rotate.tsx` and the kit items it uses: `use-composed-refs`, `use-in-view`, `use-reduced-motion`.

npm dependencies: `class-variance-authority`.

## Usage

```tsx
import { WordRotate, wordRotateVariants } from "@/components/portfolio/word-rotate"
```

## Examples

### Demo

Cycle the one word that changes in your headline. It plays through once within five seconds and settles on the first word, and screen readers hear a single sentence.

```tsx
import { WordRotate } from "@/components/portfolio/word-rotate"
import { typography } from "@/lib/typography"

export default function WordRotateDemo() {
  return (
    <div className="mx-auto max-w-5xl py-12 md:py-16">
      <h1 className={typography.display}>
        I design <WordRotate words={["interfaces", "systems", "brands", "prototypes"]} tone="highlight" />
      </h1>
    </div>
  )
}
```

### Mid-sentence

In the middle of a title, the slot keeps the widest word's width, so the words after it never move.

```tsx
import { WordRotate } from "@/components/portfolio/word-rotate"
import { typography } from "@/lib/typography"

export default function WordRotateMidSentence() {
  return (
    <div className="mx-auto max-w-4xl py-12 md:py-16">
      <h2 className={typography.title}>
        Building <WordRotate words={["calm", "fast", "accessible", "honest"]} /> software for small teams.
      </h2>
    </div>
  )
}
```

### In Body Copy

It works in body copy too: a status line with a custom screen-reader label, where `fit="word"` eases the width so the full stop follows each place.

```tsx
import { cn } from "@/lib/utils"
import { WordRotate } from "@/components/portfolio/word-rotate"
import { typography } from "@/lib/typography"

export default function WordRotateInBodyCopy() {
  return (
    <p className={cn(typography.lead, "w-full max-w-md")}>
      Currently working from{" "}
      <WordRotate
        words={["Lisbon", "a train to Porto", "anywhere with good coffee"]}
        fit="word"
        srLabel="Lisbon, mostly"
        className="font-medium text-foreground"
      />
      .
    </p>
  )
}
```

### Tones

`highlight` makes the rotating word the accent, `muted` lets it recede, `default` blends it into the line.

```tsx
import { WordRotate } from "@/components/portfolio/word-rotate"
import { typography } from "@/lib/typography"

export default function WordRotateTones() {
  return (
    <dl className="flex w-full max-w-md flex-col gap-6">
      <div className="flex flex-col gap-1.5">
        <dt className={typography.meta}>highlight</dt>
        <dd className="font-heading text-3xl leading-tight">
          Say hello in <WordRotate words={["English", "Português", "Español"]} tone="highlight" />
        </dd>
      </div>
      <div className="flex flex-col gap-1.5">
        <dt className={typography.meta}>muted</dt>
        <dd className="font-heading text-3xl leading-tight">
          Based in Lisbon, <WordRotate words={["mostly", "usually", "for now"]} tone="muted" />
        </dd>
      </div>
      <div className="flex flex-col gap-1.5">
        <dt className={typography.meta}>default</dt>
        <dd className="font-heading text-3xl leading-tight">
          Shipping <WordRotate words={["every week", "on Fridays", "quietly"]} />
        </dd>
      </div>
    </dl>
  )
}
```

## API Reference

### WordRotate

Drop it inline in any heading or paragraph; it inherits the font. Words change only while the
component is on screen and the tab is visible; with reduced motion the first word stays put.
By default the words play once within 5 s and settle on the first word.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `words` (required) | `string[]` | — | Words (or short phrases) to cycle through, in order. The first one is shown before JS runs, under reduced motion and when cycling ends. |
| `tone` | `"default" \| "highlight" \| "muted"` | `"default"` | `highlight` makes the word the accent color, `muted` lets it recede, `default` inherits the line's color. |
| `fit` | `"widest" \| "word"` | `"widest"` | `widest` reserves the width of the widest word, so the line never reflows or changes height. `word` eases the width to each word and re-flows the text after it; use it only where the line can't wrap differently (a short line, or the word at the end of a heading with room to spare). |
| `interval` | `number` | `2600` | Longest time each word stays on screen, in ms. Without `loop` the whole pass must end within 5 s (WCAG 2.2.2), so words get less time when the list needs it: about 1 s each for four words, and at least 0.8 s, so a list of more than five words shows only its first five. With `loop` every word gets the full interval. |
| `loop` | `boolean` | `false` | Keep cycling forever. Off by default: the words play once, within 5 s, while the component is on screen, and settle back on the first word. Content that keeps moving for more than 5 s needs a visible pause control (WCAG 2.2.2), so when you turn this on, wire a button to `paused`. |
| `paused` | `boolean` | `false` | Stop cycling (the current word stays). |
| `srLabel` | `string` | — | Text for assistive tech. Defaults to the words as an English list: "interfaces, systems, and brands". Set it for other languages. |

Also accepts every `span` prop.