From 2aed8b7661f00385ba9423350de5be046cc0df1b Mon Sep 17 00:00:00 2001 From: Jonathan Peris Date: Sun, 17 May 2026 00:21:06 +0000 Subject: [PATCH] docs: plan portfolio design overhaul --- DESIGN.md | 909 ++++++++++++++++++++++++++++++++++++++++------------- PRODUCT.md | 487 +++++++++++++++++++++++----- 2 files changed, 1097 insertions(+), 299 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index a9be4eb..0dd1533 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,258 +1,725 @@ ---- -version: alpha -name: Jonathan Peris Developer Portfolio -description: "Systems-console portfolio for a senior backend engineer: precise, dark, operational, and proof-oriented." -colors: - primary: "#4ADE80" - background: "#08120D" - surface: "#101C15" - elevated: "#17271D" - border: "#294333" - border-strong: "#3B604A" - text: "#EEF8F0" - muted: "#B2C8B9" - dim: "#758B7C" - accent: "#4ADE80" - accent-light: "#86EFAC" - accent-dim: "#22C55E" - cyan: "#22D3EE" - purple: "#C084FC" - amber: "#F59E0B" - rose: "#FB7185" -typography: - display: - fontFamily: DM Sans - fontSize: 4rem - fontWeight: 800 - lineHeight: 1 - letterSpacing: "-0.06em" - h1: - fontFamily: DM Sans - fontSize: 3.5rem - fontWeight: 800 - lineHeight: 1.05 - letterSpacing: "-0.05em" - h2: - fontFamily: DM Sans - fontSize: 2rem - fontWeight: 750 - lineHeight: 1.1 - letterSpacing: "-0.04em" - body: - fontFamily: DM Sans - fontSize: 1rem - fontWeight: 400 - lineHeight: 1.65 - letterSpacing: "0em" - small-mono: - fontFamily: JetBrains Mono - fontSize: 0.75rem - fontWeight: 600 - lineHeight: 1.4 - letterSpacing: "0.08em" -rounded: - sm: 6px - md: 12px - lg: 18px - xl: 28px -spacing: - xs: 4px - sm: 8px - md: 16px - lg: 24px - xl: 40px - xxl: 64px -components: - page: - backgroundColor: "{colors.background}" - textColor: "{colors.muted}" - card: - backgroundColor: "{colors.surface}" - textColor: "{colors.text}" - rounded: "{rounded.md}" - padding: 24px - card-hover: - backgroundColor: "{colors.elevated}" - textColor: "{colors.text}" - rounded: "{rounded.md}" - button-primary: - backgroundColor: "{colors.primary}" - textColor: "{colors.background}" - rounded: "{rounded.sm}" - padding: 12px - button-secondary: - backgroundColor: "{colors.surface}" - textColor: "{colors.accent-light}" - rounded: "{rounded.sm}" - padding: 12px - button-secondary-hover: - backgroundColor: "{colors.elevated}" - textColor: "{colors.accent}" - rounded: "{rounded.sm}" - padding: 12px - chip: - backgroundColor: "{colors.surface}" - textColor: "{colors.accent-light}" - rounded: "{rounded.sm}" - padding: 8px - chip-muted: - backgroundColor: "{colors.background}" - textColor: "{colors.dim}" - rounded: "{rounded.sm}" - padding: 8px - card-outline: - backgroundColor: "{colors.border}" - textColor: "{colors.text}" - rounded: "{rounded.md}" - padding: 16px - card-outline-hover: - backgroundColor: "{colors.border-strong}" - textColor: "{colors.text}" - rounded: "{rounded.md}" - padding: 16px - terminal: - backgroundColor: "{colors.background}" - textColor: "{colors.text}" - rounded: "{rounded.lg}" - padding: 16px - terminal-prompt: - backgroundColor: "{colors.background}" - textColor: "{colors.accent-dim}" - rounded: "{rounded.sm}" - padding: 4px - tag-cyan: - backgroundColor: "{colors.surface}" - textColor: "{colors.cyan}" - rounded: "{rounded.sm}" - padding: 8px - tag-purple: - backgroundColor: "{colors.surface}" - textColor: "{colors.purple}" - rounded: "{rounded.sm}" - padding: 8px - tag-amber: - backgroundColor: "{colors.surface}" - textColor: "{colors.amber}" - rounded: "{rounded.sm}" - padding: 8px - tag-rose: - backgroundColor: "{colors.surface}" - textColor: "{colors.rose}" - rounded: "{rounded.sm}" - padding: 8px ---- - -## Overview - -This design system supports `PRODUCT.md`: a proof-oriented portfolio for Jonathan Peris, a senior backend/platform engineer. The interface should feel like an operating console, deployment ledger, trace viewer, or systems manual — not like a generic portfolio template. - -The visual mood is dark green-black, precise, calm, and technical. It should communicate engineering maturity: clear hierarchy, restrained motion, strong text contrast, and small operational details that reward technical visitors without slowing down recruiters. - -The strongest design idea is **developer-ish but not gimmicky**: routes, manifests, chips, ledgers, traces, shell affordances, and repository cards are welcome; fake danger, hacker-roleplay, neon overload, and illegible cyberpunk effects are not. - -## Colors - -- **Background (`#08120D`)** anchors the site in a dark operational workspace. -- **Surface (`#101C15`)** and **elevated (`#17271D`)** separate cards, panels, and terminal areas without bright boxes. -- **Text (`#EEF8F0`)** is used for important copy and headings. -- **Muted (`#B2C8B9`)** is the default long-form reading color. -- **Dim (`#758B7C`)** is reserved for metadata, timestamps, route labels, and secondary captions. -- **Accent (`#4ADE80`)** is the primary interaction and status color. It implies healthy systems, deploy readiness, and availability. -- **Accent light (`#86EFAC`)** can highlight hover states, active labels, and emphasized links. -- **Cyan, purple, amber, and rose** are supporting syntax/status colors. Use sparingly for language dots, stack tags, or code-like semantics. - -Use the accent color as a precision instrument, not a flood fill. Large panels should stay dark; green should mark state, focus, and the most important calls to action. +# DESIGN.md — Jonathan Peris Portfolio Overhaul + +_Last audited: 2026-05-17T00:17:09Z_ + +## Design intent + +The redesign should feel like the same site, only sharper. Preserve the dark technical operator aesthetic, but make every console metaphor earn its place by improving clarity, proof, or conversion. + +The current visual language is strong enough to keep: + +- dark green-black background, +- subtle grid/noise overlays, +- terminal/YAML/system-status language, +- route-like navigation, +- monospace metadata, +- neon green accent system, +- restrained cards and borders, +- hidden shell/easter egg. + +The overhaul should not introduce a generic SaaS/agency visual system. It should turn the existing “small systems manual” direction into a premium, legible, proof-led portfolio. + +## Design diagnosis + +### Strengths + +- Memorable hero: large `Jonathan Peris` wordmark-like heading creates a strong first impression. +- Distinct aesthetic: backend-console mood fits Jonathan’s .NET/Azure/backend architecture positioning. +- Clear availability: `Open to remote roles + consulting` appears immediately. +- Strong technical signals: .NET, Azure, production systems, architecture, delivery discipline. +- Good base interaction model: route nav, resume CTA, LinkedIn CTA, social links, hidden terminal. +- Avoids common portfolio clichés: no stock illustrations, generic gradient hero, or empty “passionate developer” language. + +### Weaknesses to address + +- Hero copy can be more outcome-specific. +- Current YAML card is attractive but partially redundant. +- `View resume` is visually primary while `contact` is secondary; this may not match consulting goals. +- Stylized labels can obscure meaning for non-engineer visitors. +- Some sections are sparse relative to the page length. +- Card modules risk becoming repetitive if every section has the same rhythm. +- Workbench/repository sections need stronger proof framing. +- Very dim labels and small monospace text may reduce readability. + +## Brand attributes + +Use these as design filters: + +- Senior, not flashy. +- Technical, not cryptic. +- Calm under production pressure. +- Pragmatic architecture over architecture theater. +- Dark, precise, operational, slightly playful. +- Brazilian remote-first engineer comfortable with US teams. +- Reliable systems manual, not startup landing page. + +## Visual principles + +### 1. Console as structure, not decoration + +Use terminal/YAML/repo metaphors only where they help visitors parse content. + +Good uses: + +- hero operating profile, +- capability maps, +- experience logs, +- case files, +- contact packet, +- hidden shell. + +Risky uses: + +- decorative fake code with no new information, +- obscure labels without plain-English support, +- too many `status: healthy` cards saying the same thing. + +### 2. Proof before atmosphere in lower sections + +The hero can carry atmosphere. The rest of the page must carry evidence: + +- outcomes, +- domains, +- stacks, +- shipped artifacts, +- project purpose, +- production constraints, +- repository links. + +### 3. Hybrid labels + +Keep technical labels, but pair them with plain-English intent. + +Examples: + +```text +TRACE 01 — Profile packet / how I work +TRACE 02 — Capability map / what I help with +TRACE 03 — Experience trace / selected roles +TRACE 04 — Workbench / public proof +TRACE 05 — Contact packet / open channel +``` + +### 4. Conversion without salesiness + +The site can ask for action directly without breaking the aesthetic. + +Use: + +- `Start conversation`, +- `Contact on LinkedIn`, +- `Email Jonathan`, +- `View resume.pdf`, +- `Open GitHub`. + +Avoid over-cute CTAs where clarity matters. `run contact.sh` can be a flourish, but the accessible label should be clear. + +## Information architecture + +Recommended page order: + +1. Hero / operating profile. +2. Profile packet / how Jonathan works. +3. Capability map / what Jonathan helps with. +4. Experience trace / selected roles and domains. +5. Workbench / public proof and case files. +6. Repository tail / curated artifacts. +7. Contact packet / final CTA. +8. Footer / social links / hidden shell clue. + +## Hero design specification + +### Current hero pattern + +Left: + +- availability pill, +- huge name, +- role line, +- one-sentence lede, +- resume/contact buttons, +- operating signal strip. + +Right: + +- YAML deploy ledger card. + +This layout should remain, but the copy hierarchy should change. + +### Recommended hero wireframe + +```text +┌────────────────────────────────────────────────────────────────────┐ +│ jp. /profile /trace /workbench CTA │ +├────────────────────────────────────────────────────────────────────┤ +│ [available: remote roles + select consulting] │ +│ │ +│ Jonathan Peris ┌─ operating-profile.yaml │ +│ Backend architecture for │ status: available │ +│ production .NET systems. │ best_for: │ +│ │ - .NET modernization │ +│ I help teams clarify boundaries, │ - Azure delivery │ +│ ship safer releases, and keep │ - reliability work │ +│ critical systems operable after launch. │ signals: │ +│ │ - 12+ yrs production │ +│ [Start conversation] [View resume.pdf] │ - remote BR -> US │ +│ └─────────────────────────│ +│ [12+ yrs] [.NET/Azure] [Remote] [Architecture + delivery] │ +└────────────────────────────────────────────────────────────────────┘ +``` + +### Hero A/B variants + +#### Variant A — Resume-first + +Primary button: `View resume` +Secondary button: `Contact on LinkedIn` + +Best for recruiter traffic. + +#### Variant B — Contact-first + +Primary button: `Start conversation` +Secondary button: `View resume.pdf` + +Best for consulting and high-intent referrals. + +#### Variant C — Split intent + +Primary button group: + +- `Hiring? View resume` +- `Need architecture help? Contact` + +Best when audience is mixed and traffic is not yet segmented. + +## Color system + +Current tokens already use OKLCH and should remain broadly intact. + +### Existing mood + +- Background: near-black green. +- Surface: dark green-grey. +- Border: muted green-grey. +- Text: off-white/green-white. +- Accent: neon green. +- Support accents: cyan, purple, amber, rose. + +### Adjustments + +1. Increase contrast for muted body copy and tiny labels. +2. Reserve brightest green for primary actions and active status. +3. Use support accents by content type, not randomly: + - green: primary CTA / availability / status, + - cyan: cloud/platform/delivery, + - purple: architecture/modeling, + - amber: experience/timeline, + - rose: warnings, constraints, incident/reliability notes. + +### Suggested semantic roles + +```css +--intent-primary: var(--color-green); +--intent-platform: var(--color-cyan); +--intent-architecture: var(--color-purple); +--intent-delivery: var(--color-amber); +--intent-risk: var(--color-rose); +``` ## Typography -Use **DM Sans** for both display and body text. The brand should feel modern, legible, and engineered rather than editorial or ornamental. +### Keep + +- DM Sans for readable body/display text. +- JetBrains Mono/Fira Code for metadata, tags, route labels, YAML, and shell affordances. + +### Improve + +- Increase paragraph line-height where text is long. +- Avoid making important content too dim or too small. +- Use monospace as accent, not as the default reading mode. + +### Hierarchy target + +- H1: extremely large, but responsive with controlled wrapping. +- Section H2: large enough to reset attention after hero. +- Card H3: clear, plain-language titles. +- Metadata: small but contrast-safe. + +## Layout rhythm + +### Current risk + +Some vertical gaps feel atmospheric but can read as unfinished. The page has enough total content, but rhythm should be tightened so each scroll reveals meaningful proof. + +### Recommended rhythm + +- Hero: spacious, cinematic. +- Profile: medium density, editorial. +- Capability: denser grid; easy to scan. +- Experience: timeline/log rhythm. +- Workbench: larger case-file cards with varied spans. +- Repository tail: compact list/table. +- Contact packet: strong final block. + +## Component specifications + +### Availability pill + +Purpose: immediate status. + +Content examples: + +```text +available: remote roles + select consulting +operator status: available +remote-first / Brazil -> US teams +``` + +Design: + +- Green dot plus text. +- High enough contrast to read quickly. +- Should not be the only place availability appears. + +### Operating profile card + +Replace or evolve `deploy-ledger.yaml`. + +Recommended content: + +```yaml +operator: Jonathan Peris +mode: senior backend / consulting +best_for: + - production .NET systems + - Azure delivery discipline + - architecture recovery + - reliability after launch +signals: + - 12+ years production software + - finance / automotive / education + - remote Brazil to US teams +``` + +Design: + +- Keep code-block/YAML style. +- Use syntax-style color accents sparingly. +- Add line-height for readability. +- Avoid duplicating hero signals verbatim. + +### Signal strip + +Current signals are useful. Keep but refine. + +Recommended copy: + +- `12+ yrs` / `shipping production software` +- `.NET + Azure` / `primary backend lane` +- `Remote` / `Brazil -> US teams` +- `Systems` / `architecture + delivery ownership` -Use **JetBrains Mono** for: +### Section label -- route-style labels (`/profile`, `/trace`, `/workbench`), -- metadata and timestamps, -- shell content, -- manifest/YAML snippets, -- small tags and status chips. +Current `TRACE NN` works. Add hybrid naming. -Large headings should be compact and assertive, with tight negative tracking. Avoid decorative serif display type for this version; the product direction is operational clarity, not magazine polish. +Design: -## Layout +```text +TRACE 02 +Capability map / what I help with +``` -The layout should read like a technical dossier: +Use metadata label plus plain-language subtitle where useful. -1. **Hero / command surface:** immediate name, availability, role, remote context, resume/contact CTAs, and a manifest-like proof panel. -2. **Profile packet:** concise summary of Jonathan's value proposition and operating principles. -3. **Capability map:** stack grouped by language, backend, architecture, cloud, data, and frontend. -4. **Experience trace:** chronological production history with the current role visually elevated. -5. **Workbench:** curated featured projects before dynamic repository tail. -6. **Repository tail and footer:** more proof and socials, without exposing the shell trigger. +### Profile proof strip -Spacing should be generous enough to feel calm, but dense enough to preserve a systems-console rhythm. Prefer grids, ledgers, and cards over large decorative illustrations. +Add below profile paragraphs. -## Elevation & Depth +Layout: -Depth is subtle and mostly structural: +```text +[boundaries] [tests + CI/CD] [production ownership] [remote teams] +``` -- 1px borders for cards and panels. -- Low-opacity green glows only on hero atmosphere, active states, and hover emphasis. -- Noise/dot overlays may add texture, but must stay quiet and never reduce text readability. -- Avoid glassmorphism that makes text sit on unstable backgrounds. +or compact rows: -Hover states can lift a card with a stronger border and shadow, but the base page should remain still and professional. +```text +01 define boundaries that reduce operational cost +02 ship with tests and delivery feedback loops +03 document systems so the next engineer can operate them +04 keep architecture pragmatic under production constraints +``` -## Shapes +### Capability card -Use mostly rectangular cards with modest rounding: +Move from pure skill list to problem-oriented cards. -- `6px` for chips, buttons, and compact tags. -- `12px` for cards and code panels. -- `18px` to `28px` for large hero/terminal surfaces. +Card schema: -Do not use pill shapes everywhere. Reserve pills for availability/status indicators and high-level signals. +```text +/path/backend-architecture +title: Architecture recovery +helps_with: unclear ownership, service boundaries, modularization +stack: CQRS, DDD, clean architecture, .NET APIs +``` -## Components +### Experience trace entry + +Recommended schema: + +```text +00 Jul 2023 — Present +Software Engineer @ Derivative Path +Domain: financial platforms +Stack: .NET 8, SQL Server, CQRS, Azure DevOps +Impact: backend modules for accounting/fiscal workflows; maintainable delivery in production platform +``` + +Design: + +- Keep timeline/log feel. +- Make company/role clear. +- Add domain chips if possible. +- Avoid long paragraphs without scan anchors. + +### Workbench case file + +Current project cards should become proof-first cards. + +Schema: + +```text +CASE 01 / runtime lab +Speedy Bird +signal: cross-platform native UI experiment +proof: Lynx + TypeScript + CI/CD + browser deploy +actions: Source / Live +``` + +Use `signal`, `proof`, `stack`, and `actions` consistently. + +### Repository tail + +Design as a compact repo index. + +Schema: + +```text +repo: blazor-mudblazor-starter +summary: Blazor + MudBlazor starter template +signal: reusable frontend/backend starter +stack: C# / Blazor +links: source / site +``` + +Consider showing fewer repos with better labels rather than more raw rows. + +### Contact packet + +Add a strong final CTA before footer. + +Wireframe: + +```text +/contact_packet.yaml +status: available for remote roles + select consulting +best_fit: + - backend architecture + - .NET/Azure modernization + - delivery/reliability cleanup +channels: + - LinkedIn + - email +artifact: resume.pdf + +[Start conversation] [View resume] [Open GitHub] +``` + +## Interaction design ### Navigation -Navigation may use route-like labels and should stay sticky. Keep the resume/contact path visible and obvious. +- Keep sticky/nav route styling. +- Add visible contact action or make `resume.pdf` less monopolizing depending on CTA experiment. +- Active section indication would improve orientation on long page. + +### Hidden shell + +Keep as an easter egg. It reinforces the brand and adds personality. + +Requirements: + +- Must not block normal keyboard navigation. +- Must have accessible dialog labeling. +- Should respect reduced motion if animated. +- Analytics event `shell_open` can measure whether it is discovered. + +### Project links + +Project cards should clearly separate: + +- Source, +- Live/demo, +- Docs if available. + +Use descriptive labels for accessibility, not only “Source” repeated without context. + +## Responsive design + +Test breakpoints: + +- 390px mobile, +- 768px tablet, +- 1024px small laptop, +- 1440px desktop. + +### Mobile order + +1. Nav/logo/compact CTA. +2. Availability pill. +3. Name. +4. Value proposition. +5. Primary/secondary CTA. +6. Signal strip. +7. Operating profile card. +8. Profile/capability/proof. + +### Mobile concerns + +- H1 must not cause awkward overflow. +- YAML card should wrap cleanly or become a compact card. +- Nav links may need horizontal scroll, menu, or reduced labels. +- CTA buttons should stack with clear tap targets. +- Cards should not rely on hover-only affordances. + +## Accessibility checklist + +- Maintain semantic headings in page order. +- Ensure `aria-label`s on icon-only links. +- Ensure focus-visible states on all links/buttons. +- Keep touch targets at least 44px where practical. +- Avoid low-contrast dim metadata for important text. +- Do not rely solely on green to communicate state. +- Honor `prefers-reduced-motion` for reveal and cursor effects. +- Terminal dialog should trap or cycle focus appropriately and close with Escape. +- Repeated “Source” and “Live” links should include context via accessible labels. + +## A/B test design details + +### Variant implementation approach + +Start lightweight: + +- Derive variant from query param, e.g. `?variant=contact-first`. +- Store in `localStorage` for repeat consistency. +- Include variant in every `trackEvent` payload. +- Keep default as current or safest variant. + +Possible variants: + +```ts +const VARIANTS = { + cta: "resume-first" | "contact-first" | "split-intent", + heroCopy: "stack" | "production-dotnet" | "legible-traffic", + card: "bio-ledger" | "best-for" | "case-status", + labels: "stylized" | "hybrid", + workbench: "project-grid" | "case-files" | "repo-tree", +}; +``` + +### Experiment cards + +#### Experiment A — CTA order + +Control: + +```text +[View resume] [Contact on LinkedIn] +``` + +Variant: + +```text +[Start conversation] [View resume.pdf] +``` + +Success metric: + +- Contact click rate. +- Resume click rate. +- Total CTA click rate. + +#### Experiment B — Hero copy + +Control: + +```text +Backend architecture / .NET / Azure +``` + +Variant 1: + +```text +Backend architecture for production .NET systems +``` + +Variant 2: + +```text +Backend systems that stay legible under real traffic +``` + +Success metric: + +- First-viewport CTA clicks. +- Bounce rate. +- Scroll to profile/capability sections. + +#### Experiment C — Operating card + +Control: + +```yaml +operator/location/status/focus/runtime +``` + +Variant: + +```yaml +mode/best_for/signals +``` + +Success metric: + +- Hero CTA clicks. +- Scroll depth to Workbench. +- Time on page. + +#### Experiment D — Label clarity + +Control: + +```text +Profile packet +Capability map +Experience trace +Workbench +``` + +Variant: + +```text +Profile packet / how I work +Capability map / what I help with +Experience trace / selected roles +Workbench / public proof +``` + +Success metric: + +- Scroll depth by section. +- Nav click rate. +- Reduced bounce from non-GitHub referrers. + +#### Experiment E — Workbench proof framing + +Control: + +- Current project card grid. + +Variant: + +- Case-file cards with `signal`, `proof`, and explicit action labels. + +Success metric: + +- Project source/live click-through. +- Scroll depth past Workbench. +- Contact clicks after Workbench. + +#### Experiment F — Final contact packet + +Control: + +- Footer with social icons only. + +Variant: + +- Full-width terminal/YAML contact card above footer. + +Success metric: + +- Footer/contact click-through. +- Resume clicks after scroll >75%. + +## Content examples + +### Hero copy candidates + +```text +Backend architecture for production .NET systems. +``` -### Hero manifest / deploy ledger +```text +I help teams clarify boundaries, ship safer releases, and keep critical systems operable after launch. +``` -The hero proof panel may resemble YAML, a deploy ledger, or a terminal card. It should contain truthful product signals: experience, current lane, location/remote fit, availability, and key stack. +```text +.NET / Azure systems that stay legible under real traffic. +``` -### Cards +### Capability cards -Cards should be information-dense but not cramped. Each card needs a clear title, metadata, and one concise proof statement. Featured project cards can use language color accents, but the surrounding panel should remain in the main palette. +```text +Architecture recovery +For teams with unclear service ownership, tangled domains, or fragile modernization paths. +``` -### Tags and chips +```text +Delivery discipline +CI/CD, tests, release loops, and documentation that keep architecture honest after launch. +``` -Tags are metadata, not decoration. Use them to make stack and domain fit scannable. Avoid turning every noun into a chip. +```text +Production backend systems +C#, .NET, SQL Server, PostgreSQL, Azure, Docker, and APIs designed for ownership. +``` -### Terminal / shell +```text +Remote technical leadership +Brazil-to-US collaboration, async clarity, and engineering decisions written down. +``` -The shell is a progressive enhancement and personality layer. It is an easter egg, not a visible feature: do not add an "open shell" button, footer instruction, or explicit activation hint in the primary UI. It must not be the only way to access resume, contact, stack, or availability information. Keyboard behavior should be predictable after discovery: `Enter` submits, `Escape` closes, and focus is visible. +### Final CTA -### CTAs +```text +If your backend needs clearer boundaries, safer delivery, or calmer production ownership: +[Start conversation] [View resume.pdf] +``` -Primary CTA: resume/contact/hire path. Secondary CTA: GitHub, LinkedIn, and project links. Do not expose the shell as a CTA. CTAs should use clear verbs and preserve native link behavior. +## QA checklist for implementation -## Do's and Don'ts +Before merging an overhaul: -### Do +- Run typecheck/build with Bun in this repo. +- Inspect desktop, tablet, and mobile in browser. +- Verify no horizontal overflow at 390px. +- Verify resume route and external social/project links. +- Verify analytics events still fire and include variant labels. +- Verify hidden shell still opens/closes and returns focus. +- Verify reduced motion behavior. +- Confirm Lighthouse/accessibility issues are not introduced. -- Make seniority, .NET/backend depth, remote readiness, and availability visible immediately. -- Use operational metaphors: traces, manifests, ledgers, workbench, status, signals. -- Keep claims tied to proof: current role, project links, stack groups, and work history. -- Keep contrast high and body copy readable on dark backgrounds. -- Use CSS-first motion and respect reduced-motion preferences when adding new animation. -- Keep frequently edited content in `src/lib/data.ts`. +## Design success criteria -### Don't +The redesign succeeds if: -- Don't make the site feel like a crypto, hacker, cyberpunk, or gaming landing page. -- Don't hide contact or resume behind easter eggs. -- Don't overuse neon green, blur, scanlines, or fake terminal noise. -- Don't inflate claims beyond what `PRODUCT.md`, work history, and repositories support. -- Don't replace human clarity with clever labels; route-style copy must still be understandable. -- Don't introduce heavy runtime dependencies for purely decorative effects. +- The site still feels unmistakably like a dark systems-console portfolio. +- A recruiter can understand Jonathan’s role and download the resume quickly. +- A consulting lead can understand what backend problems Jonathan helps solve. +- Workbench cards communicate proof, not only project names. +- The page ends with an intentional contact path. +- A/B variants can be tested without duplicating the whole page. diff --git a/PRODUCT.md b/PRODUCT.md index 1ac6835..e18d016 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -1,118 +1,449 @@ -# PRODUCT.md +# PRODUCT.md — Jonathan Peris Portfolio -## Product +_Last audited: 2026-05-17T00:17:09Z_ -`jonathanperis.github.io` is Jonathan Peris's public developer portfolio and proof-of-work hub. It should help hiring managers, technical interviewers, engineering leaders, collaborators, and consulting prospects understand who Jonathan is, what he is strong at, and why he is credible for backend/system architecture work. +## Product summary -The site is not a generic resume template. It is a compact technical artifact that should feel like it belongs to an engineer who builds production systems, cares about delivery, and can still make the interface memorable. +Jonathan Peris Portfolio is a personal technical website for a senior backend/.NET/Azure engineer. It should make Jonathan easy to evaluate for remote senior engineering roles, backend architecture consulting, and technical leadership work while preserving the current dark systems-console aesthetic. -## Primary Outcomes +The site is not a generic resume page. It is a compact “systems manual” for Jonathan’s operating style: reliability before theater, boundaries with a reason, and delivery as part of architecture. -1. **Convert qualified visitors into conversations.** Make it easy for the right person to contact Jonathan for remote roles, backend/platform engineering work, or selected architecture consulting. -2. **Communicate seniority quickly.** Within the first screen, make clear: 12+ years, .NET/Azure/fintech depth, remote collaboration, and production ownership. -3. **Show proof, not just claims.** Use work history, featured repositories, live project links, and concise engineering principles to demonstrate taste and execution. -4. **Keep the portfolio maintainable.** The content model, components, and design tokens should be simple enough for future agents and humans to update safely. +## Current product state -## Audience +The current homepage already has a strong identity: -### Hiring managers and recruiters +- Dark green-black operator console mood. +- Route-like navigation: `/profile`, `/trace`, `/workbench`. +- Large identity-first hero with `Jonathan Peris` as the anchor. +- Availability signal: “Open to remote roles + consulting.” +- Clear stack signal: backend architecture / .NET / Azure. +- YAML/status-card metaphor: `deploy-ledger.yaml` and `healthy`. +- Hidden terminal/easter egg that reinforces the developer persona. +- Profile, capability, experience, featured work, repository tail, and footer/social sections. -They need a fast answer to: "Is this person relevant for a senior software engineering role?" The page should foreground current role, availability, location/remote context, contact links, resume, and technology fit. +The next product move is an overhaul that keeps this aesthetic but makes it more purposeful, proof-led, and conversion-oriented. -### Engineering leaders and staff/principal engineers +## Primary audiences -They need evidence of judgment. The site should emphasize systems thinking, reliability, boundaries, delivery discipline, and concrete project/work examples instead of buzzword density. +### 1. Senior engineering recruiters and hiring managers -### Technical interviewers +They need to answer quickly: -They need scannable signals: stack, past domains, architecture vocabulary, repository links, and enough implementation detail to start a deeper technical conversation. +- What role is Jonathan best suited for? +- Is he senior enough for architecture and ownership? +- What stack does he operate in? +- Has he worked with production systems and distributed teams? +- Where is the resume/contact path? -### Consulting prospects and collaborators +### 2. Technical leaders and founders evaluating consulting help -They need to know where Jonathan can help: backend architecture, .NET modernization, fintech/business systems, cloud delivery, and pragmatic implementation. +They need to answer: + +- What kinds of backend problems can Jonathan help with? +- Is this mostly coding, architecture, delivery, or team enablement? +- Does he understand reliability, operations, and maintainability? +- Can he work remotely across Brazil/US team contexts? +- How do we start a conversation? + +### 3. Engineers and technical peers + +They need to answer: + +- Is the craft credible? +- Are the public repos and projects interesting? +- Does the site feel technically intentional or decorative? +- Can they inspect code, docs, and experiments? + +## Product goals + +1. Increase clarity in the first viewport without flattening the personality. +2. Make contact and resume actions obvious throughout the page. +3. Turn the console aesthetic from decoration into information architecture. +4. Show proof of production-oriented backend work through case-file language, repository artifacts, and anonymized outcomes. +5. Improve scanning for recruiters while keeping enough technical depth for engineers. +6. Preserve the current dark systems/manual aesthetic. +7. Provide A/B testing hooks for message, CTA, and layout experiments. + +## Non-goals + +- Do not replace the site with a bright corporate SaaS template. +- Do not add stock illustrations, generic headshot-first hero patterns, or generic “passionate developer” copy. +- Do not make the interface so terminal-like that non-engineering visitors cannot understand it. +- Do not overfit for a single public project; the site should represent Jonathan’s overall career and operating style. +- Do not remove the hidden shell/easter egg unless analytics or usability testing shows it causes confusion. ## Positioning -Jonathan is a production-focused software engineer with 12+ years of experience, centered on .NET, fintech/business systems, cloud delivery, and clean architecture. The strongest positioning is: +### Current positioning + +> Backend architecture / .NET / Azure + +> I build backend systems that can be understood, operated, and changed after they meet production traffic. + +This is strong and on-brand. It should be tightened into a more outcome-forward promise. + +### Recommended positioning variants for testing + +#### Variant A — recruiter/senior-role focused + +> Senior .NET engineer for production backend systems. -> Senior backend/platform engineer for teams that need durable business systems, clear architecture boundaries, and reliable delivery. +Subcopy: -Supporting signals: +> 12+ years building financial, automotive, education, healthcare, retail, and infrastructure software with clean boundaries, tests, and delivery discipline. -- Current software engineering work at Derivative Path on financial modules: General Ledger, Hedge Accounting, Fiscal Calendar, and DerivativeEDGE. -- Deep .NET ecosystem experience: .NET Core+, ASP.NET Core, Entity Framework, MAUI, Blazor. -- Architecture vocabulary backed by years of delivery: CQRS, DDD, microservices, hexagonal architecture, clean architecture, SAGA pattern. -- DevOps/cloud literacy: Azure, Azure DevOps, Docker, Kubernetes, CI/CD. -- Curiosity beyond the main lane: Rust, Go, Python, TypeScript, WebAssembly, game/dev experiments, and performance-oriented repositories. +#### Variant B — consulting/problem focused -## Brand Personality +> Backend architecture for teams that need calmer production systems. -- **Competent, not loud.** Confident language, restrained claims, proof-first framing. -- **Systems-minded.** The interface may borrow from terminals, runbooks, traces, manifests, and deployment ledgers. -- **Human but concise.** Keep small personal touches and easter eggs, but do not let them obscure professional clarity. -- **Pragmatic.** Architecture is framed as a way to reduce operational cost, not as decoration. -- **Remote-ready.** Brazil-based, US-team-friendly, async-capable, comfortable with distributed engineering work. +Subcopy: -## Content Principles +> I help .NET/Azure teams clarify service boundaries, improve delivery paths, and keep critical systems operable after launch. + +#### Variant C — current aesthetic refined + +> Backend systems that stay legible under real traffic. + +Subcopy: + +> .NET, Azure, SQL, CQRS, DDD, CI/CD, and production ownership — applied with enough pragmatism to survive the next incident. + +## Core user journeys + +### Journey 1 — Recruiter evaluation + +1. Land on homepage. +2. Understand identity, role, availability, stack, location, and remote status in under 10 seconds. +3. Click `resume.pdf` or `View resume`. +4. Optionally inspect experience trace and featured work. +5. Contact on LinkedIn/email. + +Success metrics: + +- Resume click-through rate. +- LinkedIn click-through rate. +- Scroll depth to `Experience trace`. +- Time to first CTA click. + +### Journey 2 — Consulting lead + +1. Land on homepage. +2. Understand backend problems Jonathan solves. +3. Read capability map and workbench case files. +4. See proof of reliability/delivery/architecture mindset. +5. Click contact CTA. -1. **Lead with the current value proposition.** The hero should quickly communicate role, experience, availability, location/remote fit, and contact path. -2. **Every section earns its space.** Avoid filler sections; each block should answer a likely visitor question. -3. **Prefer specific nouns.** Use concrete domains, modules, stacks, and project names over generic adjectives. -4. **Separate signals from proof.** A short signal chip can say ".NET + Azure"; a nearby section should explain where that shows up in work. -5. **Keep availability current.** The current stance is: open to remote roles and selected backend architecture consulting. -6. **Keep generated repository data subordinate.** Dynamic GitHub projects are useful proof, but the curated workbench/featured list should set the narrative. +Success metrics: -## Required User Journeys +- Contact click-through rate. +- Scroll depth to `Workbench`. +- Clicks on case-file/project cards. +- Return visits from same referrer. -### Recruiter fast path +### Journey 3 — Engineer peer inspection 1. Land on homepage. -2. See availability, role, experience, and remote/location context immediately. -3. Click LinkedIn, email/contact, or resume without scrolling deeply. +2. Explore Workbench/public repos. +3. Inspect GitHub/source/live links. +4. Discover hidden shell or deeper technical details. + +Success metrics: + +- Source link clicks. +- Live project clicks. +- Repository tail clicks. +- Hidden shell activation, if measurable. + +## Product audit findings + +### What works + +- Strong, coherent identity: dark terminal/manual aesthetic matches backend architecture positioning. +- Large hero is memorable and not generic. +- Availability, stack, years of experience, remote status, and operating style are visible. +- CTA buttons are clear in the hero. +- The copy avoids many portfolio clichés. +- Route-style IA and YAML card are distinctive and technically aligned. + +### Friction points + +- The first viewport leads with name and mood before a sharper outcome promise. +- The YAML card repeats bio/status data instead of communicating stronger value or service fit. +- `View resume` is primary, but consulting/contact intent is secondary. +- Section labels such as `Profile packet`, `Trace`, and `Workbench` are stylish but may need plain-English reinforcement. +- Workbench and repository areas should become stronger proof sections, not just project/repo lists. +- Small muted text and dense monospace areas may be low contrast for some users. +- Repeated dark cards can flatten the page if every section uses the same module style. + +## Overhaul strategy + +Keep the current aesthetic; increase the product clarity. + +### 1. Hero: sharpen the promise + +The hero should answer: + +- Who is this? +- What does he specialize in? +- What problem does he solve? +- What action should I take? + +Recommended hero content architecture: + +```text +[availability/status pill] +Jonathan Peris +Backend architecture for production .NET systems. +I help teams clarify boundaries, ship safer releases, and keep critical systems operable after launch. +[Start conversation] [View resume.pdf] +[12+ yrs] [.NET/Azure] [Remote BR→US] [Architecture + delivery] +``` + +### 2. YAML/status card: make it strategic + +Replace repeated bio content with a stronger operating profile: + +```yaml +operator: Jonathan Peris +mode: senior backend / consulting +best_for: + - .NET systems with unclear boundaries + - Azure delivery pipelines that need discipline + - teams modernizing production services + - reliability work after the first incident +signals: + - 12+ years production software + - finance / automotive / education / healthcare + - remote Brazil to US teams +``` + +### 3. Navigation: keep routes, add clarity + +Current: + +```text +/profile /trace /workbench resume.pdf +``` + +Recommended test: + +```text +/profile /capabilities /trace /workbench contact +``` + +or keep the current labels but add plain-language titles inside sections: + +```text +TRACE 01 — Profile packet / how I work +TRACE 02 — Capability map / what I help with +TRACE 03 — Experience trace / selected roles +TRACE 04 — Workbench / public proof +TRACE 05 — Contact packet / open channel +``` + +### 4. Profile: narrative plus scan layer + +Keep the two paragraphs, then add a compact proof strip: + +- Defines service boundaries and ownership models. +- Ships production software with tests and CI/CD feedback loops. +- Works across finance, automotive, education, healthcare, retail, insurance, and infrastructure. +- Remote-first with Brazil-to-US team experience. + +### 5. Capability map: make it buyer-friendly + +Reframe from pure skill taxonomy into “problems I help solve”: + +- Architecture recovery: service boundaries, modularization, CQRS/DDD where useful. +- Backend delivery: .NET APIs, SQL-backed systems, tests, release discipline. +- Cloud operations: Azure, CI/CD, Docker/Kubernetes, observability paths. +- Team enablement: documentation, ownership, handoff clarity, pragmatic standards. + +### 6. Experience trace: add impact shape + +Each role should show: + +- Role/company/domain. +- Stack. +- Responsibility/impact. +- Production context. + +Use concise log/case language, not only resume paragraphs. + +### 7. Workbench: convert projects into proof + +Use a case-file card structure: + +```text +CASE 01 / runtime lab +Speedy Bird +signal: cross-platform native UI experiment +proof: Lynx + TypeScript + CI/CD + browser deploy +actions: Source / Live +``` + +For public technical repos, emphasize what each proves about Jonathan: + +- architecture discipline, +- performance engineering, +- cross-platform experimentation, +- documentation quality, +- release automation. + +### 8. Repository tail: curate, do not dump + +The repository tail should feel intentional. Prefer a curated “latest artifacts” or “lab index” over an unweighted list. + +Add filtering or grouping later if needed: + +- architecture samples, +- performance labs, +- game/runtime experiments, +- docs/reference builds. + +### 9. Footer: final conversion card + +End with a clear final action: + +```yaml +contact_packet: + status: available for remote roles + select consulting + best_channel: LinkedIn / email + artifact: resume.pdf +``` + +Buttons: + +- Start conversation +- View resume +- Open GitHub + +## A/B testing plan + +Use lightweight URL/query variants or configuration flags first. Avoid shipping a heavy experimentation platform unless traffic volume warrants it. + +### Experiment 1 — CTA priority + +- A: Primary `View resume`; secondary `Contact on LinkedIn`. +- B: Primary `Start conversation`; secondary `View resume.pdf`. + +Hypothesis: B improves consulting/contact clicks; A may perform better for recruiter traffic. + +Measure: + +- `cta_click` by label. +- LinkedIn/email clicks. +- Resume clicks. +- Scroll depth. + +### Experiment 2 — Hero value proposition + +- A: `Backend architecture / .NET / Azure`. +- B: `Backend architecture for production .NET systems`. +- C: `Backend systems that stay legible under real traffic`. + +Hypothesis: B improves recruiter comprehension; C preserves stronger brand personality. + +Measure: + +- CTA click rate from first viewport. +- Bounce rate. +- Time on page. + +### Experiment 3 — YAML card content + +- A: Current deploy ledger bio/status card. +- B: Strategic `best_for`/`signals` card. +- C: Mini case-file/status report card. + +Hypothesis: B improves perceived relevance for consulting leads without changing the visual aesthetic. + +### Experiment 4 — Section labels + +- A: Current stylized labels only: `Profile packet`, `Capability map`, `Experience trace`. +- B: Hybrid labels: `Profile packet / how I work`, `Capability map / what I help with`. + +Hypothesis: B improves comprehension for non-engineer visitors while retaining the console aesthetic. + +### Experiment 5 — Workbench framing + +- A: Current project cards. +- B: Case-file cards with `signal`, `proof`, and `actions`. +- C: Repository-tree interface with expandable cards. + +Hypothesis: B increases proof comprehension; C may increase technical visitor exploration. + +### Experiment 6 — Proof density + +- A: Current narrative density. +- B: Add proof chips and anonymized outcomes. + +Hypothesis: B improves trust and scroll depth, especially for hiring managers. + +### Experiment 7 — Final CTA block + +- A: Current small footer/social links. +- B: Full-width `contact_packet` terminal card before footer. + +Hypothesis: B increases contact clicks from users who scroll past Workbench. + +## Analytics events to keep/add + +Existing `trackEvent` usage should be extended consistently. + +Recommended events: + +```text +cta_click { label, location, variant } +nav_click { label, variant } +project_click { slug, action, variant } +repo_click { name, variant } +contact_click { channel, location, variant } +resume_click { location, variant } +shell_open { method, variant } +scroll_depth { bucket, variant } +``` + +## Implementation roadmap -### Engineering evaluator path +### Phase 1 — Documentation and measurement -1. Read hero and profile packet. -2. Scan capability map and engineering principles. -3. Inspect experience trace and featured projects. -4. Open GitHub/live project links. +- Update `PRODUCT.md` and `DESIGN.md` with this audit and design plan. +- Ensure current analytics labels distinguish hero/nav/footer CTA locations. +- Keep current visual implementation untouched except documentation. -### Curious developer path +### Phase 2 — Same-aesthetic hero overhaul -1. Notice the console/runbook aesthetic. -2. Discover the interactive shell only through the easter egg. -3. Explore repositories and social links. +- Test contact-first vs resume-first CTA order. +- Replace YAML card content with `best_for`/`signals` content. +- Add a `/contact` or equivalent route/action in nav. -## Functional Requirements +### Phase 3 — Proof-led middle and lower page -- Static Astro site deployable to GitHub Pages. -- React-powered interactive portfolio component. -- Build-time GitHub project fetching where configured, with safe fallbacks. -- Resume route and/or resume CTA available from primary navigation. -- Contact/social links available in hero/footer and keyboard/screen-reader accessible. -- Hidden shell/easter egg preserved as progressive enhancement; it must not have a visible CTA or explicit activation instructions in the primary UI, and core content must remain useful without it. -- Analytics events may track outbound/social/resume interactions, but must not block navigation. +- Add profile proof strip. +- Reframe capability map as problems Jonathan helps solve. +- Convert workbench cards to case-file cards. +- Add final `contact_packet` CTA. -## Non-Goals +### Phase 4 — A/B test infrastructure -- Do not become a blog platform unless there is an explicit content strategy. -- Do not over-index on animation at the expense of readability or performance. -- Do not present Jonathan as a full-service agency or generic freelancer marketplace profile. -- Do not hide the resume/contact path behind clever terminal interactions. -- Do not let the site look like a cryptocurrency, cyberpunk, gaming, or hacker-roleplay landing page. +- Add query/local variant support, e.g. `?v=contact-first`. +- Persist variant per visitor with localStorage if needed. +- Include variant in analytics events. -## Product Quality Bar +### Phase 5 — Polish and accessibility -- **Clarity:** A first-time visitor should understand Jonathan's profile in under 10 seconds. -- **Credibility:** Claims should map to work history, project links, or explicit engineering principles. -- **Accessibility:** Text contrast, focus states, semantic structure, and reduced-motion friendliness matter. -- **Performance:** Static output should remain lightweight; decorative effects should be CSS-first. -- **Maintainability:** Data that changes often belongs in `src/lib/data.ts`; global visual decisions belong in `DESIGN.md` and CSS tokens. -- **Trust:** External links should be accurate, current, and safe (`rel="noreferrer noopener"`). +- Improve text contrast for dim labels. +- Validate focus states and hit targets. +- Test 390px, 768px, 1024px, and desktop widths. +- Respect `prefers-reduced-motion` for reveal/typing effects. -## Success Signals +## Definition of done for the overhaul -- More qualified inbound contact via LinkedIn/email/Workana/GitHub. -- Recruiters can quickly identify Jonathan as a senior .NET/backend engineer. -- Technical reviewers can cite specific projects, architecture choices, and domains. -- Future redesigns remain consistent because `PRODUCT.md` defines product intent and `DESIGN.md` defines visual rules. +- First viewport communicates role, audience, value, and action in under 10 seconds. +- Contact and resume CTAs are visible in hero and near page end. +- Workbench reads as proof, not just decoration. +- Repository tail is curated and understandable. +- The page still feels like Jonathan’s dark systems manual. +- Accessibility checks pass for contrast, keyboard focus, labels, and reduced motion. +- A/B variants are documented and measurable.