srbhr--resume-matcher/.impeccable.md

Design Context — Resume Matcher

This file is the source of truth for design decisions. All impeccable:* skills (audit, critique, polish, animate, etc.) read this before making any visual changes.

Last updated: 2026-04-09

---

Users

Resume Matcher serves three overlapping audiences, all of whom land on the same UI:

• Anxious job seekers — individuals tailoring resumes during active job hunts, often in the evening or late at night. They are the largest group. They want fast, calming, low-friction help — not AI hype, not clever features they have to learn. The interface should reduce their stress, not amplify it.
• Tech-savvy DIY users — developers, designers, and technical PMs who run things locally with Ollama. They notice and reward craft. They will silently judge a generic SaaS aesthetic and respect a distinctive one. They forgive complexity if it feels intentional.
• Students and early-career applicants — first-time job seekers who need confidence and clarity. The interface should feel encouraging without being patronizing or playful. It should make them feel like adults using a serious tool.

Common job-to-be-done: take an existing resume + a job description and produce a tailored resume + cover letter that the user can ship as a PDF. Speed and trustworthiness matter more than power-user features.

Use context: usually a desktop or laptop browser. Often used in 30–60 minute focused sessions. Frequently in the evening. Rarely on mobile (resume editing is a desktop task), but the marketing/landing surfaces still need to read on mobile.

---

Brand Personality

Three words: Confident · Honest · Crafted

• Confident — quiet confidence, not loud. The interface doesn't need to shout that it's powerful. A confident UI does its job and trusts the user to notice the care.
• Honest — no inflated copy, no AI hype, no decorative ornament that doesn't earn its place. Status messages are direct. Errors say what's wrong. Buttons say what they do.
• Crafted — every pixel feels intentional. Typography, spacing, alignment, and color choices all reward closer inspection. The kind of interface that makes a designer say "someone cared about this."

The product should feel like a well-designed printed object translated to the browser — a museum exhibit caption, a fabric label on a well-made jacket, a printed monograph — rather than a SaaS web app.

---

Aesthetic Direction

Foundation: Swiss International Style

The existing visual identity is documented in docs/portable/swiss-design-system/. That pack is the canonical reference for tokens, components, layouts, anti-patterns, and the AI prompt template. Read it before making any visual change.

Non-negotiable from that pack:

• rounded-none everywhere
• Hard offset shadows only — never blurred
• Three-font hierarchy (serif headers, sans body, mono labels uppercase)
• Canvas (#F0F0E8) as the page background — never pure white
• Hyper Blue (#1D4ED8) used sparingly for one primary action per region

Pull toward brutalist/raw

The current implementation is conservative within the Swiss frame. Push it harder:

• Bigger type contrast — a section header should look 3× as important as body, not 1.2×
• More poster-like moments on landing/marketing surfaces (oversized hero text, asymmetric grids, intentional whitespace as a graphic element)
• Status squares and labels should feel like industrial signage, not UI chrome

Pull toward refined minimal

The current implementation also has some accumulated SaaS habits to strip. Pull the other direction:

• Restrict the accent palette ruthlessly. Hyper Blue should feel rare. Most screens should be black ink on Canvas, with one moment of color.
• Strip the half-finished dark mode (see Theme below).
• Replace decorative icons with mono functional ones, or with nothing.
• Prefer typography hierarchy over decorative containers. Not everything needs a card.

Theme

Light theme only. The dark mode mapping in globals.css is half-finished and dilutes the brand. It should be removed in the audit cleanup. Swiss style works best on the warm Canvas background; that's the brand.

The .dark block in globals.css will be flagged for removal.

References (for the right feel)

• A printed monograph from a design publisher (Lars Müller, Phaidon)
• A 1970s technical manual cover
• A museum exhibit caption card
• An off-white linen book jacket

Anti-references (what this should NOT look like)

• Generic SaaS resume builders (Resume.io, Zety, etc. — soft pastel palettes, rounded everything, decorative icons, "AI ✨" badges)
• Vercel/Linear/Stripe template-y look (elegant but no longer distinctive — every YC company looks like this)
• Glassmorphism, gradient text, neon-on-dark, pastel cyan/purple AI palettes
• Hero-metric template ("3M+ resumes optimized · ⭐ 4.9 stars · 50+ countries")
• Card carousels, decorative sparklines, identical icon-headed cards

---

Design Principles

Five rules that should guide every design decision in this codebase. When in doubt, read these.

1. Hard edges, soft warmth

The geometry is brutally hard (rounded-none, hard shadows, 1–2px black borders). The background is warm (Canvas #F0F0E8, not pure white). This combination is the brand: confident structure, no clinical chill. Never ship pure white surfaces. Never ship rounded corners.

2. One primary action per region

Hyper Blue is rare on purpose. Each logical screen region (a card, a panel, a page) should have at most one primary blue action. Everything else is outline, ghost, or text-only. If a screen has two blue buttons, one of them is wrong.

3. Type does the heavy lifting

Hierarchy comes from weight and size, not from color or boxes. A section header should be 2.5–3× the body size with bold weight. A label should be small monospace uppercase with tracked-wider letter-spacing. The type system carries the design — decoration is forbidden.

4. Asymmetric, anti-centered layouts

Left-aligned by default. Whitespace varies for hierarchy (more space above an important header, less above a continuation paragraph). Symmetric center-aligned content is the lazy default — push toward asymmetric compositions where the eye is pulled deliberately.

5. No AI decorative tells

The full anti-pattern list is in docs/portable/swiss-design-system/anti-patterns.md. The non-negotiable bans:

• No gradient text ever (background-clip: text + gradient)
• No side-stripe borders (border-left: Npx solid color for accent stripes)
• No glassmorphism (decorative blur, glow borders)
• No gradients of any kind in surface backgrounds
• No decorative icons — only functional, mono-color
• No bounce/elastic easing — exponential decel only
• No animating layout properties — transform/opacity only
• No nested cards, no card carousels, no hero-metric templates
• No bare emoji in product UI, no ✨ badges

If any of these appear, that's a bug.

---

Constraints

• Stack: Next.js 16 (App Router), React 19, Tailwind CSS v4, TypeScript 5
• Forbidden font families (per impeccable + brand): Inter, Roboto, Open Sans, system defaults, Space Grotesk (currently in use — flagged for replacement), DM Sans/Serif, Plus Jakarta Sans, Outfit, Fraunces, Newsreader, Playfair Display, Cormorant, IBM Plex *, Instrument *
• Accessibility target: WCAG 2.2 AA. 4.5:1 text contrast minimum, full keyboard navigation, visible focus indicators, ARIA on interactive elements, semantic landmarks.
• Performance budgets: Next.js 16 App Router conventions; no barrel imports from lucide-react; heavy components (TipTap, dnd-kit) lazy-loaded; First Load JS under 250KB per route.
• i18n: en, es, zh, ja currently supported — text length varies, layouts must accommodate longer translations.
• PDF rendering: print stylesheet exists in globals.css; resume preview must render identically to the printed PDF.