Official design system contract for agentjob.io — fast-hiring AI platform (tokens, bilingual rules, typography, components, and layout).

agentjob.io Design System (Contract)

agentjob.io is a fast-hiring platform: an AI agent matches candidates to the right jobs and applies for them automatically. The design identity is light, calm, and precise — the agent does the work in the background, so the interface never raises its voice.

It is built for any market and any language: Arabic and English are both first-class, and the system works symmetrically in LTR and RTL.

1. Voice & Communication Principles

Short sentences, second person, active voice:
- EN: "Your agent applied to 3 jobs."
- AR: "قدّم وكيلك على ٣ وظائف."
Finished actions, never intentions:
- The agent reports completed work: "Applied to…" rather than "Will try to…".
Explicit automation promises:
- State precisely what automation will execute before it runs ("Apply to 90%+ matches for me").
Calm restraint:
- No emoji, no exclamation marks, no superlatives ("the best", "revolutionary").
- Sentence case everywhere; never uppercase labels (Arabic has no case — keep both scripts parallel).
Brand name syntax:
- The name is always lowercase Latin agentjob.io, even within Arabic sentences.

2. Bilingual & Directional Rules (RTL & LTR)

Root definition: Set lang and dir on <html lang="ar" dir="rtl"> or <html lang="en" dir="ltr">. Every component respects this context.
Logical CSS only: Use logical utilities (ms-, me-, ps-, pe-, start-, end-, inset-inline-*, margin-inline-*, padding-block-*). Never hardcode physical left/right.
Directional icon mirroring: Only navigational and directional icons mirror (arrow); semantic icons such as bolt, check, and clock never mirror.
Numerals:
- Arabic-Indic digits (٣) in Arabic narrative copy.
- Latin digits (3) in English copy.
- mono data (timestamps, logs, IDs) uses Latin digits in both languages.
Typography leading: Arabic body text uses body-ar (28px line height) via :lang(ar). Arabic heroes use display-ar.

3. Color Tokens (`tooling/tailwind/theme.css`)

3.1 Surfaces & Neutrals

--surface (#fafaf7 light / #111315 dark): The page canvas — warm paper white, never sterile white.
--surface-raised (#ffffff light / #1a1d20 dark): Cards, job rows, sheets, inputs, and dropdown menus.
--surface-sunken (#f2f1ec light / #22262a dark): Hover states for secondary controls, neutral badges, avatar backgrounds, and toggle off-tracks.
--line (#e7e5de light / #2c3035 dark): Decorative dividers and card borders at rest.
--line-strong (#80848b light / #6b7178 dark): Control borders (inputs, chips, switches, secondary buttons) — guaranteed ≥ 3:1 contrast.

3.2 Inks (Typography)

--ink (#16181d light / #eef0ee dark): Primary text and titles.
--ink-muted (#5d6169 light / #a3a9ad dark): Secondary text, subtitles, and metadata (company, location, date).

3.3 The Brand: Agent (Deep Teal)

--agent (#0f5c55 light / #5fc7b8 dark): Primary brand color, primary buttons, match scores, active states, and agent speech.
--agent-strong (#0b4a44 light / #7fd6c9 dark): Hover and active states for agent fills.
--agent-soft (#e3f1ee light / #15302c dark): Tinted backgrounds for selected chips, agent badges, and match score tracks.
--on-agent (#ffffff light / #0b1f1c dark): High-contrast label color on agent fills.

3.4 Speed & Automation: Spark (Amber Gold)

--spark (#e8a33d light / #f2b75a dark): Automation accent exclusively — auto-apply button, active switch, and agent live dots. Limit to one spark element per screen.
--spark-strong (#d9922a light / #f5c677 dark): Hover state for spark fills.
--on-spark (#16181d light / #111315 dark): Text and icons on spark fills.
--spark-soft (#fbf0dc light / #2e2410 dark): Background for "Auto-applied" badges.
--spark-ink (#8a5a12 light / #f2b75a dark): Text color on spark-soft.

3.5 Feedback Tokens

--positive (#1f7a4d light / #6fd39c dark) & --positive-soft (#e2f2e8 / #13301f): Success states, applications sent, interviews scheduled.
--danger (#b4412b light / #f08a73 dark) & --danger-soft (#f8e6e1 / #3a1c15): Errors, rejected or failed submissions.
Always accompany feedback colors with explicit words or icons, never color alone.

4. Typography Scale

Token	Family	Weights	Usage
`display`	Readex Pro	500 (48px / 56px)	Hero headlines. Arabic and Latin match harmoniously.
`display-ar`	Readex Pro	500 (44px / 64px)	Arabic hero headline with optimized leading.
`title`	Readex Pro	500 (28px / 36px)	Page titles and primary section heads.
`heading`	Instrument Sans / IBM Plex Sans Arabic	600 (18px / 26px)	Job titles in cards, dialog titles.
`body`	Instrument Sans	400 (16px / 24px)	Default Latin reading text.
`body-ar`	IBM Plex Sans Arabic	400 (16px / 28px)	Arabic reading text with comfortable vertical rhythm.
`small`	Sans stack	400 (14px / 22px)	Metadata, helper descriptions, table cells.
`label`	Sans stack	500 (12px / 16px)	Badges, chips, form labels. Sentence case.
`mono`	IBM Plex Mono	400 (13px / 20px)	Agent activity logs, timestamps, IDs.

5. Shape, Spacing & Shadows

Spacing rhythm (4px base):
- --space-1 (4px), --space-2 (8px), --space-3 (12px), --space-4 (16px)
- --space-6 (24px), --space-8 (32px), --space-12 (48px), --space-16 (64px)
Corner radii:
- --radius-sm (6px): Inputs, badges, checkboxes.
- --radius-md (10px): Buttons, menus, company logo containers.
- --radius-lg (16px): Cards, job rows, sheets, agent feeds.
- --radius-pill (999px): Filter chips, auto-apply switch.
Shadow:
- --shadow-soft: 0 1px 2px rgba(22, 24, 29, 0.06), 0 4px 16px rgba(22, 24, 29, 0.05). Used on hover and floating menus only. Cards at rest use --line borders.

6. Components Catalog (`@repo/ui`)

All agentjob.io components are exported directly and through the AgentJob namespace from @repo/ui:

import {
	JobCard,
	MatchScore,
	AgentFeed,
	StatusSteps,
	AgentJobButton,
	AgentJobBadge,
	AgentJobChip,
	AgentJobSwitch,
	AgentJobTextField,
	AgentJobWordmark,
	AgentJobIcon,
} from "@repo/ui";

JobCard: Primary application block (title, company, logo, location, type, posted, match score, tags, status, actions).
MatchScore: High-precision circular SVG indicator showing percentage match (0-100%).
AgentFeed: Real-time chronological action feed documenting agent background operations.
StatusSteps: Clear multi-stage application pipeline (todo, current, done).
Switch: Auto-apply toggle with the spark illumination and bolt icon.
Chip: Interactive multi-select filter pill with count indicator and checkmark.
Wordmark: Canonical brand rendering — agentjob in ink, .io in agent.

agentjob.io Design System

On this page