JM Design Guidelines

This document is the design system and the working method behind my portfolio. I built the site the way I build products for clients: with a written process, a token-based visual language, documented components and an accessibility bar that is checked, not assumed.

The visual concept is "the file, not the render". Instead of polished screens, the site borrows the language of the tools where the work happens: labeled frames, redlines, comment pins and a grid you can switch on.

Five rules that settle arguments

Principles exist to make decisions faster. When two options look equally good, the one that follows more of these wins.

The UI/UX process, end to end

Eight phases, grouped into the six stages shown on the portfolio. The order is the default; the loop is the rule. Each phase ends on an agreed criterion, so a client always knows where we are.

Success is defined at kickoff with a metrics baseline, tracked in usability rounds (task success, SUS) and read again after launch.

Working agreements

Communication is part of the deliverable. These are the defaults I propose on every engagement; we adjust them at kickoff.

Color

Light-first. A warm paper and a near-black ink do most of the work, and ink is the brand. Sticky fills bring the FigJam energy; strong hues are their text-safe siblings.

Primitives · paper & ink

Primitives · sticky fills

Primitives · strong hues & functional

Semantic tokens

Components reference intent, never primitives: a change is a token swap, not a redesign. Every ratio below was measured.

Rules

• Sticky fills always carry ink text, never white. Colored text uses a strong hue (violet-600, teal-700, coral-700).
• Never set text in a sticky color on paper (1.2–2.1:1). Every new pair gets measured and recorded here.

Typography

Four families with four jobs, chosen to be uncommon but never hard to read.

Scale

Rules

• Body line length between 45 and 75 characters (max-width: 68ch).
• Hierarchy comes from size and the italic, not bold. The highlighter (em) goes on the one word that carries the meaning.
• Minimum sizes: 13px for UI text, 10px for mono meta, 18px for Mynerve, which never carries anything a task depends on.

Spacing & layout

A 4pt base with a 10-step scale: steps 1–4 inside components, 4–6 between them, 7–9 between sections. If a value isn't on the scale, the layout is wrong, not the scale.

A 12-column fluid grid inside a 1200px container with 24px gutters. Press Alt + G (⌥G on a Mac) on any page to see it.

Shape, borders & elevation

The system is wireframe-first: modest corners, 1px hairlines, dashed lines for things that aren't final. Depth comes from borders and layering; shadows are small, offset and always ink. Icons are rare on purpose, because words are clearer.

Motion

Motion explains: things draw themselves, pins drop in, connections animate in the order a designer would make them. Nothing moves for decoration and everything respects prefers-reduced-motion.

• Enter with emphasized, exit with exit, everything else standard.
• Only animate transform and opacity (and SVG stroke-dashoffset). No layout animation.
• Reduced motion: all durations drop to ~0, reveals render in their final state and the 3D story becomes still images.

Annotation language

The layer that makes the portfolio look like a working file: a small vocabulary borrowed from Figma and classic redlining, each mark with one fixed meaning.

The personality, rebuilt for this system

v2 brings back the voice of my first portfolio. Every element was kept, adapted or dropped against two filters: does it read as me and does it pass the accessibility bar.

Component library

Every example below uses the site's production CSS, and components consume semantic tokens only. The library also holds the section header, process step, case frame and annotation marks.

Button

Buttons trigger actions; links go places. A view has one primary button. Labels are verb-first and never longer than three words.

• Hover lifts it 1.5px, active presses it 2px, disabled fades to .45 opacity with the label still readable.
• Minimum height 44px. Small (32px) lives only in the toolbar, with 8px of space around it.
• Focus ring: 2px focus color, 3px offset, visible on every variant, never removed.
• Anchors styled as buttons are real links; buttons that don't navigate are real <button> elements.

Tag

Tags label things: skills, status, categories. They are not buttons and never navigate.

• Mono 10.5px uppercase, padding 3 × 10, pill shape, 1px border.
• Max three tags per case card. If you need more, the card needs a better title.
• The status-pill pulsing dot is decorative and hidden on mobile.

Frame

The frame is the primary container, standing in for an artboard. It always has a label, may have selection handles, and may host annotation marks positioned absolutely inside it.

• Solid = final. Dashed = placeholder or in progress. Selected = hovered case or the hero.
• Frames sit on bg-elevated; the page sits on bg. Never nest more than two frames.
• Labels are accurate: a 1200-wide frame says 1200.

Comment pin

A pin marks a conversation. Its bubble shows author, role and the comment. Pins are interactive: hover, click or focus to open; Esc closes; one open at a time.

• A 24 × 24 teardrop with a mono number; the bubble is 190–240px wide.
• A real control: role="button", tabindex="0", Enter or Space toggles, Esc closes all.
• The bubble opens to the right; .pin--left flips it near the right edge.

Toolbar

A quiet editor toolbar: wordmark, page navigation, the EN / PT switch and a Designer view pill (Alt + G) that shows the grid and turns the pointer into an inspector, like Figma.

• Sticky, 60px, translucent elevated background with blur, 1px bottom border.
• The current section is marked with aria-current="true" and a 2px underline.
• Below 860px the nav becomes a sheet toggled by a "Menu" button with aria-expanded and aria-controls.
• Designer view is a toggle with aria-pressed; Esc closes it.

Page patterns

Case study template

The structure every project write-up follows. Someone should get the story from the headings alone; the details reward those who read on.

1. Summary: client, role, timeline and status, then "In 30 seconds": the problem, what I did, where it landed.
2. Overview: the product, who it's for and what I owned.
3. Challenge: what was broken, for whom, and the constraints.
4. Process: the steps this project really took, each tied to one of the six stages.
5. Solution: key screens with annotations, the decisions behind them and the system pieces built.
6. Validation: what was tested and what changed, when the project had room to test.
7. Outcome: what was handed off, what shipped, what didn't and why.
8. Reflection: one thing I'd change, or what I'd measure next. Honest, short.

Content & voice

The voice is a designer explaining her work to a smart colleague: direct, specific, warm, no jargon for its own sake.

Accessibility

Target: WCAG 2.2 level AA on every page, checked before every release. Ticked items are verified on v2.5.0.

• Text contrast ≥ 4.5:1 (1.4.3) for all body and label text.
• Non-text contrast ≥ 3:1 (1.4.11) for input borders, button boundaries and focus rings.
• Focus visible (2.4.7 / 2.4.11) with a 2px ring that is never obscured by sticky elements.
• Target size ≥ 24 × 24 (2.5.8, new in 2.2) with 44px default for primary controls.
• Keyboard operable (2.1.1): all controls including pins, toggles and mobile nav.
• Reduced motion respected (2.3.3): animations disabled under the OS preference.
• Semantics: one h1 per page, landmarks, skip link first; decorative marks are aria-hidden.
• Toggle state exposed: aria-pressed / aria-expanded / aria-current where relevant.
• Reflow (1.4.10): no horizontal scroll at 320px CSS width; tables scroll within their container.
• Screen reader pass and automated audit (VoiceOver, NVDA, axe): scheduled.

Handoff & tokens

Handoff transfers intent. Specs live in Dev Mode and in tokens; annotations explain what the canvas can't show: logic, conditions, edge cases.

• Naming: category-property-variant-state, with no value words in semantic names ("brand", never "green").
• Source of truth: tokens.json in the W3C DTCG format, mirrored by Figma variables with the same names.
• Ready frames: marked "Ready for dev", every value a variable, all states present, responsive at 375, 768 and 1440.
• Annotations for intent: what happens on click, validation rules, transitions, copy that changes.
• Names match code (Button/Primary/Md ↔ .btn.btn--primary); a walkthrough and a design QA plan close it.

Changelog

Semantic versioning: major for a renamed or removed token or a changed component API, minor for anything new, patch for fixes. Every change is checked against the principles, the accessibility checklist and the token dependency rule.

2.5.0 · “Canvas, reviewed” · Sep 2026

• Changed: the site moved to jessmonteiro.com, with a sitemap, a canonical pt-BR version and share previews in both languages.
• Fixed: accessibility gaps from a full review. Designer view needs Alt + G, the closed mobile menu leaves the tab order, the 3D chapters stay readable to screen readers and focus never hides under sticky bars.
• Changed: American English throughout and a line-by-line rewrite of the Portuguese against a shared glossary.
• Added: an "In 30 seconds" summary and stage labels on every case, and this template rewritten for freelance work.
• Added: responsive images, non-blocking Portuguese and a custom scrollbar in the cursor's style.
• Changed: these guidelines cut to about a third of their length.