JobJitsu Design System
Visual and interaction language for the desktop app. Color, type, and logo foundations live in BRAND_GUIDELINES.md.
Production tokens, themes, and component variants: ../design-system/README.md
This document covers structure, naming, motion overview, accessibility overview, icons, and illustration.
1. Design Pillars (UI)
- Native feel, local power — Light chrome, crisp motion, keyboard-first where it counts.
- Dark mode first — Default: Midnight Ink (
#0B0A1A) with Electric Teal (#2DD4BF) accents. Light mode is intentional, not an afterthought. - Invisible agent — Surface queue, calendar, and status calmly — never a spaceship cockpit.
- Privacy always visible — Status bar: belt mark or Agent · On-device badge.
- One job per view — Each screen has a primary purpose; secondary actions stay quiet.
2. Foundations (Summary)
High-level brand anchors only. Production CSS tokens, themes, and component variants live in ../design-system/ — see DESIGN_TOKENS.md, THEME_DARK.md, and THEME_LIGHT.md. Do not treat this table as the token source of truth.
| Token | Value | Role |
|---|---|---|
| Deep Indigo | #1E1B4B | Primary brand, belt, dark surfaces |
| Electric Teal | #2DD4BF | CTAs, links, logo flap, focus |
| Teal (AA body, dark) | #14B8A6 | Body-size teal text on dark when needed |
| Midnight Ink | #0B0A1A | Dark background |
| Soft Cloud | #F8FAFC | Light background |
| Jade | #10B981 | Success |
| Amber | #F59E0B | Caution / pending |
| Inter | UI sans | 400–700 |
| JetBrains Mono | Code / logs | 400 |
Radius, spacing, and elevation should stay subtle: prefer tight desktop density over large consumer-app padding. Soft shadows only; no neon glow stacks.
3. UI Naming Guidelines
Names in the interface should match how users think about the job hunt and the agent — not internal engineering terms.
Principles
- User language first: “Follow-ups”, not “ReminderCron”.
- Stable nouns: Reuse the same word for the same concept everywhere.
- Verb clarity: Actions say what happens to data or the outside world.
- No false friends: Don’t call a draft a “throw” in navigation; metaphor belongs in microcopy, not IA.
Canonical UI Terms
| Concept | UI name | Avoid |
|---|---|---|
| Main automation | Agent | Bot, Autopilot, Worker, LLM |
| On-device intelligence | Agent / On-device | Local LLM, Cloud AI, ChatGPT (unless choosing a runtime in advanced settings) |
| Job application unit | Application | Opp, Req, Ticket |
| Pre-send holding | Queue | Pipeline (unless visualizing stages) |
| Post-send check-in | Follow-up | Chase, Ping storm |
| User rules | Preferences | Config dump, Profile hacks |
| Résumé file | Resume | CV only if locale requires |
| Approval gate | Review / Approve send | Confirm nuke |
| Privacy indicator | Agent · On-device | Local LLM, Secure sauce |
Screen & Section Titles
- Prefer nouns: “Applications”, “Follow-ups”, “Preferences”, “Agent”.
- Subtitles may use calm sentence case: “Queued and waiting for your signal.”
File & Export Names (user-visible)
JobJitsu-resume-export.pdfstyle: Product + purpose + extension.- No cryptic hashes in names the user sees.
4. Component Naming
For design specs, Storybook, and code — consistent, boring, discoverable.
Pattern
Jj{Domain}{Element}[{Variant}]
Examples: JjAgentStatusBadge, JjApplicationQueueRow, JjFollowUpCard, JjAgentPrivacyPill.
Domain Prefixes
| Prefix | Domain |
|---|---|
JjAgent | Agent status, controls, idle |
JjApplication | Application list, draft, send |
JjFollowUp | Reminders and nudges |
JjPreferences | Settings forms |
JjPrivacy | Agent on-device badge, indicators |
JjOnboarding | First-run steps |
JjLog | Agent / terminal output |
Rules
- PascalCase for components; camelCase for instances/props.
- Variants via props (
tone="success"), notJjButtonGreenSuccessLarge. - Do not encode color in the name (
TealButton); encode role (PrimaryButton). - Lucide icons: wrap as
JjIconor use Lucide names directly — do not rename “Mail” to “EnvelopeThrow”. - Prefer composition:
JjApplicationQueuecontainsJjApplicationQueueRow.
State Names (props / CSS)
Use: default, hover, focus, active, disabled, loading, success, caution, error.
Align caution with Amber and success with Jade from the brand palette.
5. Motion (brand intent)
Motion expresses presence and hierarchy, not celebration spam: confirm that something local and fast happened, guide attention to the next calm step, never block with ornament. Approved patterns (status pulse, row settle, toast rise), timing/easing tables, and reduced-motion rules live in ../design-system/ANIMATION.md. Never confetti, parallax dashboards, or motion that ignores prefers-reduced-motion.
6. Accessibility (brand intent)
Calm UI must remain usable under WCAG AA (AAA where brand contrast already allows): visible teal focus rings, keyboard-operable primary workflows, real buttons/links, live regions for toasts and errors, and never color alone to convey state. Contrast pairs, focus specs, and semantics requirements live in ../design-system/ACCESSIBILITY.md; recovery copy in ERROR_MESSAGES.md.
7. Icon Usage
Library
Lucide — MIT, open-source. Aligns with open-source values.
Style
- Stroke: 2 px
- Caps & joins: rounded
- Default size in UI: 16 or 20 px; 24 px for empty-state anchors
- Color: Indigo (
#1E1B4B) on light; white on dark; teal on hover/active for interactive icons
Role Mapping (examples)
| Action / concept | Lucide suggestion |
|---|---|
| Applications | briefcase or file-text |
| Send / apply | send |
| Follow-up | bell or mail |
| Agent | bot sparingly — prefer custom belt mark for brand moments |
| Local / privacy | belt mark or shield — prefer brand Agent · On-device pill |
| Settings | settings |
| Success | check / check-circle |
| Caution | clock or alert-triangle (amber) |
| Error | alert-circle |
Rules
- One metaphor per control — don’t stack badge + icon + emoji.
- No emoji in primary chrome.
- Decorative icons:
aria-hidden="true". Informative icons: accessible name via label oraria-label. - The teal envelope flap on the logo is sacred — do not recolor Lucide icons to invent a second “envelope brand”.
Privacy Badge
Indigo/teal pill in the status bar: text “Agent · On-device” (or “Agent ready” / “Agent unavailable”). Always present while the on-device agent path is active. Never default this label to “LLM”.
8. Illustration Style
Character
Minimal line-art. Soft Cloud or Midnight fields. Single accent: Electric Teal arcs that echo belt curves or origami folds. Geometric, modern, uncrowded.
Motifs
- Belt-like continuous curves
- Soft envelope / fold geometry (pipeline metaphor)
- Optional future mascot: origami fox with a small indigo belt — used rarely, never as UI chrome clutter
Placement
- Onboarding, empty states, about screen
- Not behind dense data tables
- Not as full-bleed noisy patterns under body text
Don’ts
- 3D glossy martial-arts stock photos
- Purple AI nebula backgrounds
- Comic-fight imagery
- Busy collages or floating sticker packs on the hero
9. Related Copy Surfaces
| Surface | Doc |
|---|---|
| Empty states | EMPTY_STATES.md |
| Notifications | NOTIFICATIONS.md |
| Errors | ERROR_MESSAGES.md |
| Success | SUCCESS_MESSAGES.md |
