sass-mohfarawati/docs/DESIGN_SYSTEM.md

Design System — mohfarawati.de

The visual language for the public site and admin. This documents the token system that already lives in app/globals.css and tailwind.config.ts, and defines the layers that are still missing (type scale, spacing rhythm) so the site has one consistent, premium base before any page is redesigned.

Source of truth for values: app/globals.css (:root + .dark). Tailwind mappings: tailwind.config.ts. This file is the usage guide for those tokens.

---

Direction: Warm Premium (work-forward)

Chosen visual direction. Every design decision serves these principles:

1. The work is the hero. Layouts lead with project imagery and a strong title hierarchy; chrome stays quiet.
2. One decisive accent. The warm red-orange brand color appears sparingly — primary CTAs, one highlighted word, active/selected states, focus. Everything else is neutral ink on light/dark surfaces. Accent is a punctuation mark, not a background.
3. Generous whitespace + restraint. Space and type hierarchy carry the premium feel — not borders, gradients, or decoration. "Too busy" is the default failure mode; cut before adding.
4. Depth, softly. Elevation via one soft shadow layer and the large 24px radius already in the tokens. Avoid stacking shadows or heavy borders.
5. Light + dark parity. Every token has a dark value; never hardcode a hex.
6. Arabic is first-class. RTL layout, no uppercase or letter-spacing on Arabic text, slightly looser line-height. Latin uses Museo, Arabic uses Dubai.

Colors and fonts are fixed by the owner and are not changed by this system — it only organizes and documents them and adds the missing scale layers.

---

1. Color tokens

All colors are HSL channel triplets consumed as hsl(var(--token)). Light is :root, dark is .dark.

Base

Token	Light	Dark	Use
--background	0 0% 100%	222 22% 8%	Page canvas
--foreground	222 24% 10%	210 20% 96%	Primary ink
--muted	220 14% 96%	222 16% 14%	Quiet fills
--muted-foreground	220 10% 42%	217 10% 64%	Secondary text

Surfaces (elevation ramp)

Token	Light	Dark	Use
--surface-1	0 0% 100%	222 22% 9%	Base card
--surface-2	220 16% 97%	222 18% 12%	Raised card / section tint
--surface-3	220 14% 94%	222 16% 15%	Highest / hover
--surface-inverse	222 24% 12%	210 20% 96%	Inverted blocks

Step surfaces 1 → 2 → 3 for hierarchy. Do not invent intermediate greys.

Brand + semantic (use sparingly)

Token	Light	Dark	Use
--brand-primary / --primary / --ring	9 73% 50%	9 78% 56%	The one accent: CTAs, highlight word, focus
--brand-secondary	12 64% 58%	12 74% 64%	Accent gradient partner, live dots
--primary-foreground	210 40% 98%	210 40% 98%	Text on accent
--destructive	0 84% 60%	0 63% 31%	Errors only

Status

Token	Light	Dark
--status-success / --status-success-soft	145 63% 42% / 145 58% 92%	145 68% 66% / 145 36% 18%
--status-warning / --status-warning-soft	36 92% 44% / 41 96% 90%	42 96% 66% / 35 40% 18%

Reserved for real state (success/warning feedback), never decoration.

Lines + hero

Token	Light	Dark	Use
--border	220 13% 90%	222 14% 18%	Default hairline
--border-strong	220 11% 82%	222 12% 26%	Emphasis divider
--hero-base / --hero-ink	260 22% 95% / 226 43% 11%	222 24% 10% / 210 20% 96%	Hero backdrop base + ink

Tailwind exposes these as bg-background, text-foreground, bg-surface-2, text-brand-primary, border-border, bg-status-success-soft, etc.

Accent budget: at most one accent-filled element per view (usually the primary CTA). Additional emphasis uses ink weight/size, not more color.

---

2. Typography

Fonts (fixed)

Script	Family	Variable	Utility	Weights
Latin (default)	Museo Sans Rounded	--font-museo	.font-latin	300, 500, 700, 900
Arabic	Dubai	--font-dubai	.font-arabic	300, 400, 700

Applied on body (Latin) and html[lang="ar"] (Arabic) in globals.css.

Type scale (to add as tokens in 2.3)

A single documented scale replaces ad-hoc sizes. Latin values; Arabic overrides noted below.

Role	Size (clamp)	Weight	Line-height	Tracking
display	clamp(2.75rem, 8vw, 5.5rem)	900	0.95	-0.03em
h1	clamp(2.25rem, 5vw, 3.5rem)	700	1.05	-0.02em
h2	clamp(1.75rem, 3.5vw, 2.5rem)	700	1.1	-0.015em
h3	1.375rem (22px)	700	1.2	-0.01em
title	1.125rem (18px)	500	1.3	0
body-lg	1.125rem (18px)	400	1.7	0
body	1rem (16px)	400	1.7	0
small	0.875rem (14px)	400 / 500	1.6	0
caption	0.8125rem (13px)	500	1.5	0
overline	0.75rem (12px)	500	1.4	0.14em, uppercase

Arabic overrides: never uppercase, never letter-spacing (breaks joins); add ~0.1 to line-height on display/h1/h2; cap weight at 700 (Dubai has no 900). The overline role for Arabic uses normal tracking and normal case.

Only two Latin weights per view in body copy (regular 400 + one bold). Reserve 900 for display only.

---

3. Radius

Token	Value	Use
--radius-surface	24px	Cards, panels, large containers (rounded-surface / lg / xl)
--radius-nested	16px	Nested elements, inputs, buttons (rounded-nested / sm / md)
--radius-pill	9999px	Pills, badges, toggles (rounded-pill)

The generous 24px surface radius is part of the premium feel — keep it consistent; do not mix arbitrary radii.

---

4. Elevation (shadows)

Token	Use
--shadow-xs / shadow-xs	Subtle lift (hairline cards)
--shadow-sm / shadow-sm	Small controls, pills
--shadow-card / shadow-card	Default raised card
--shadow-panel / shadow-panel	Floating panel / glass surface
--shadow-md, --shadow-lg	Reserved for overlays; use rarely

Discipline: most surfaces are flat with a hairline border. Raise with one shadow layer at a time. Never stack shadow-lg on nested elements.

---

5. Spacing + layout

Containers

Token	Value	Use
--container-narrow	48rem	Reading width, forms
--container-default	72rem	Standard page content
--container-wide	80rem	Galleries, wide grids
--container-admin	88rem	Admin workspace

Header: --header-height: 4.5rem.

Vertical rhythm (to formalize in 2.3)

Existing: --section-space: 3.5rem, --content-space: 1.5rem (spacing.section, spacing.content).

Premium layouts need more air. Recommended section rhythm to add:

Token	Value	Use
section-sm	3rem	Tight sections
section	5rem (mobile) → 7rem (lg)	Default between major sections
section-lg	8rem+	Hero-adjacent breathing room

Internal gaps use rem steps: 1rem, 1.5rem, 2rem.

---

6. Motion

framer-motion, restrained. Entrance pattern (see components/layout/site-hero.tsx):

• item: opacity 0→1, y 16→0, duration 0.54, ease [0.22, 1, 0.36, 1]
• container stagger: 0.13, delay 0.08

Rules: entrance + hover only; respect prefers-reduced-motion; no looping or attention-grabbing motion on content.

---

7. Component conventions

• Cards route through components/ui/app-card.tsx (AppCard with level/layer/padding). Use level to express hierarchy — do not restyle cards ad hoc.
• Buttons: one primary (accent) per view; others outline/ghost.
• Badges: success/warning variants map to status tokens; outline for neutral tags.
• Inputs: --radius-nested, --border, focus uses --focus-ring.
• Inline feedback (admin): components/admin/admin-flash.tsx.

---

8. Do / Don't

Do

• Lead with imagery and whitespace; let type hierarchy do the work.
• Use the accent once per view, deliberately.
• Keep one radius language (24 / 16 / pill) and one shadow layer.
• Test every screen in light and dark, and Arabic RTL.

Don't

• Fill backgrounds with brand color or gradients.
• Add a second accent hue.
• Apply uppercase/letter-spacing to Arabic text.
• Stack shadows or mix arbitrary radii/greys.
• Put decoration where whitespace would do.