# Mohith Portfolio Design System

This document is the implementation contract for the visual design of Mohith's portfolio. It is intended for designers, developers, and AI coding tools working on this repository.

## Product character

- Purpose: present Mohith's work, technical judgment, story, and contact paths.
- Main-site direction: editorial minimalism with neo-brutalist accents, large typography, hard borders, restrained color, and deliberate motion.
- Era direction: the `/know-more` worlds intentionally change atmosphere while preserving shared layout, accessibility, and performance rules.
- Voice: direct, grounded, technically confident, slightly playful, and free of generic marketing language.

## Typography

- Body family: Switzer Variable, weights 300 through 700, served locally with `font-display: optional` to prevent late layout and paint shifts on slow connections.
- Display family: Oswald 700 with Switzer and sans-serif fallbacks.
- Body copy: usually 15-18px with 1.6-1.75 line height.
- Small labels: 10-12px, uppercase only where the existing interface uses system-style labels.
- Headings: compact line height, strong hierarchy, and balanced wrapping. Use the display face for high-impact headings.
- Numeric data: use tabular figures.

## Core colors

| Token | Value | Use |
| --- | --- | --- |
| Canvas | `#ffffff` | Main-site background |
| Ink | `#0f172a` | Primary text and hard contrast |
| Black | `#000000` | Footer and immersive era canvases |
| Muted gray | `#828282` | Secondary controls and labels |
| Light border | `#dedede` | Main-site borders |
| Electric cyan | `#00ffff` | Selection and occasional emphasis |
| Hot pink | `#ff006e` | Limited accent use |
| Lime | `#d0ff00` | Limited accent use |
| Orange | `#ff5400` | Limited accent use |

Accent colors support hierarchy; they must not replace readable text contrast or become the only state indicator.

## Layout and spacing

- Primary content maximum width: `72rem` / Tailwind `max-w-6xl`.
- Primary horizontal padding: 10-22px on small screens, 44px on medium screens.
- Core breakpoints: 24rem (`xxs`), 30rem (`xs`), 48rem (`md`), and 75.5rem (`custom`).
- Section rhythm: 48px on mobile, 64-128px on larger screens depending on narrative importance.
- Cards use intentional clusters. Avoid adding a card when spacing or a rule can establish hierarchy.
- Minimum supported viewport width: 300px. Every route must remain free of horizontal document overflow at 440px.

## Shape, borders, and depth

- Navigation and compact controls: full pills or rounded-3xl surfaces.
- Main editorial cards: hard 3-4px slate borders with 4-8px offset shadows where the brutalist language is already present.
- Immersive era cards: translucent surfaces with subtle borders; avoid stacking blur, glow, and shadow on the same large surface.
- Standard interaction feedback is 200ms or less.
- Use shadows to clarify elevation, not as decoration on every element.

## Motion

- Animate `transform` and `opacity` by default.
- Entrance motion: 160-360ms, ease-out, small travel distances, and short stagger windows.
- Navigation transitions: controlled, interruptible, and never dependent on `display: none` during an active transition.
- Page transitions: approximately 120-160ms with no large full-page blur.
- Continuous animation must pause while off-screen or while the document is hidden.
- Respect `prefers-reduced-motion`; functionality and hierarchy must remain intact with motion disabled.
- Do not animate large blur surfaces, layout properties on large regions, or scroll position from a raw scroll handler.

## Shared component rules

- Navigation remains a centered floating pill. The collapsed state shows the brand and menu affordance; the expanded state reveals links and the AI assistant.
- Buttons and icon controls require visible focus treatment and an accessible name.
- Main calls to action use concise labels and at least a 44px touch target on mobile.
- Project cards prioritize title, outcome, role, and destination. Decorative media must not delay the text.
- Loading states should preserve the final structure and clearly identify external interactive worlds.

## Era-specific language

### Origin Story, 2020

- Palette: near-black, emerald, teal, and CRT green.
- Motifs: terminal output, scanlines, pixel details, and tactile retro controls.
- Keep the story readable before interactive toys. Never steal focus or scroll on page load.

### Design Realm, 2022

- Palette: deep teal and slate with cyan/green accents.
- Motifs: grids, tokens, component systems, design tools, and controlled motion demonstrations.
- Prefer useful demonstrations over novelty interactions or placeholder content.

### Creation Wave, 2024

- Palette: black with indigo/cyan light.
- Motifs: a dark studio, lamp interaction, AI-assisted creation, and focused shipping.
- Heavy external worlds load only after explicit user intent.

### Forward Surge, 2025-2026

- Palette: black, blue, and cool white.
- Motifs: depth, spatial cards, measurable results, hackathons, CTFs, and current achievements.
- Achievement data must be factual and dated; unfinished placeholders should not replace known results.

## Accessibility and quality bar

- Use semantic HTML and native controls.
- All interactive elements must work by keyboard and expose an accessible name.
- Maintain visible focus, sufficient contrast, meaningful alternative text, and reduced-motion support.
- Titles, descriptions, canonical URLs, Open Graph metadata, Twitter cards, robots rules, and sitemap entries must cover every public page.
- Target 90+ Lighthouse scores for Performance, Accessibility, Best Practices, and SEO on both mobile and desktop, while treating real-user performance as the final authority.

## Performance contract

- Each era loads only the code and external media it uses.
- Third-party analytics load after hydration.
- External iframes must not block the primary page shell.
- Long off-screen chapters use deferred rendering where safe.
- Canvas, WebGL, video, marquee, and animation loops pause off-screen and in background tabs.
- Images declare dimensions through Next Image or stable aspect-ratio containers to avoid layout shift.

## Source of truth

- Global tokens and shared utilities: `app/globalsV2.css`
- Fonts and global metadata: `app/layout.tsx`
- Site URLs and identity: `config/siteConfig.ts`
- Timeline content: `app/data/knowMoreTimeline.ts`
- Era implementation: `app/(site)/know-more/[era]/`

When a new UI conflicts with this document, preserve the established product character, accessibility, and performance contract before adding novelty.