MHMD Studio Docs

Appearance

Design System ​

The MHMD Studio Design System is the single source of truth for every visual, interactive, and structural decision made across the platform. It defines the design language, reusable patterns, component behavior, accessibility requirements, and implementation standards.

Document Metadata ​

PropertyValue
DocumentDesign System
Version1.0
StatusActive
OwnerMohammed El Maachi
Last UpdatedJuly 2026

Purpose ​

This document establishes every reusable visual rule used throughout MHMD Studio.

It exists to ensure:

  • Visual consistency
  • Faster development
  • Better collaboration
  • Easier maintenance
  • Predictable interfaces
  • Better accessibility

No UI element should be created without consulting this document.

Design Philosophy ​

The MHMD Studio design language can be summarized in six words:

Editorial. Technical. Calm. Intentional. Minimal. Timeless.

The interface should communicate confidence through restraint.

Users should notice the quality of execution rather than individual visual effects.

The design should feel carefully engineered instead of artistically decorated.

Core Principles ​

Everything in this design system follows these principles.

Typography creates hierarchy. ​

Color creates emphasis.

Spacing creates rhythm.

Motion creates continuity.

Components create consistency.

Content creates value.

Design Characteristics ​

The interface should feel:

  • Editorial
  • Quiet
  • Premium
  • Highly engineered
  • Spacious
  • Confident
  • Professional
  • Modern
  • Human

Never:

  • Loud
  • Flashy
  • Trendy
  • Corporate
  • Futuristic
  • Overdesigned

Visual Inspiration ​

The overall aesthetic draws inspiration from:

  • General Intelligence Company
  • Linear
  • Stripe
  • Anthropic
  • Vercel
  • Notion
  • Apple

These references should guide quality rather than imitation.

Color Philosophy ​

Color is intentionally restrained.

Hierarchy should primarily be established through:

1 Typography

2 Scale

3 Spacing

4 Layout

5 Motion

Color comes last.

Accent colors should be rare enough that users immediately recognize importance.

Color Tokens ​

Neutral Scale ​

TokenValueUsage
Background#FEFFFCPrimary canvas
Surface#FFFFFFCards
Surface Alt#F9FAF7Inputs
Foreground#171717Main text
Heading#2C2C2CHeadings
Body#444141Paragraphs
Muted#646464Secondary text
Border#DEE2DEBorders
Divider#ECEFECSeparators

Primary Accent ​

TokenValue
Primary#41A1CF

Used only for:

  • Primary CTA outlines
  • Interactive highlights
  • Links
  • Focus states

Never use it as a large background color.

Atmospheric Accent ​

TokenValue
Cerulean#0081C0

Reserved exclusively for:

  • Hero illustrations
  • Promotional cards
  • Feature highlights

Should occupy less than 5% of the interface.

Success ​

TokenValue
Success#2E8B57

Warning ​

TokenValue
Warning#D97706

Error ​

TokenValue
Error#DC2626

Color Rules ​

Use no more than:

  • 1 primary accent
  • 1 warning
  • 1 success
  • 1 destructive color

Avoid rainbow interfaces.

Every color should communicate information.

Typography Philosophy ​

Typography is the primary visual identity.

Good typography should make decoration unnecessary.

Users should understand content hierarchy before noticing colors.

Font Stack ​

Display Font ​

Primary:

PP Mondwest

Fallbacks:

  • Fraunces
  • Recoleta
  • GT Sectra

Purpose:

Editorial headings.

Hero titles.

Large statements.

UI Font ​

Primary:

AF

Fallbacks:

  • Inter
  • Geist
  • Söhne

Purpose:

Everything else.

Type Scale ​

RoleSizeWeightLine Height
Display54px4001.1
Hero48px4001.1
H140px4001.1
H232px5001.2
H327px5001.3
H422px5001.3
Body16px4001.6
Small15px4001.5
Caption13px4001.4

Typography Rules ​

Never use:

  • Centered paragraphs
  • Justified text
  • Excessive bold
  • All caps for paragraphs

Prefer:

  • Left alignment
  • Comfortable spacing
  • Moderate contrast
  • Clear hierarchy

Spacing Philosophy ​

Whitespace is an active design element.

Every layout should breathe.

Never reduce spacing merely to fit more content.

Spacing Scale ​

Base unit:

4px

Scale:

4

8

12

16

20

24

32

40

48

64

80

96

128

Always use the spacing scale.

Avoid arbitrary values.

Layout Grid ​

Desktop:

12 columns

Maximum width:

1200px

Content width:

760–820px

Reading width:

65–75 characters

Vertical Rhythm ​

Sections:

96–160px

Cards:

24–40px

Groups:

16–24px

Text:

8–16px

Buttons:

8–12px

Maintain rhythm consistently.

Border Radius ​

ElementRadius
Buttons8px
Cards16px
Inputs8px
Badges999px
Hero Cards24px
Navigation999px

Do not invent new radius values.

Borders ​

Primary border:

1px solid #DEE2DE

Avoid heavy borders.

Prefer subtle separation.

Elevation ​

The interface should rely on spacing before shadows.

Use shadows sparingly.

Levels:

Level 0

No shadow

Level 1

Small card shadow

Level 2

Floating navigation

Level 3

Modal

No component should exceed Level 3.

Glassmorphism ​

Allowed only for:

  • Navigation
  • Hero overlays
  • Floating panels

Never use glass effects for ordinary cards.

Opacity should remain subtle.

Backdrop blur:

10–20px

Responsive Breakpoints ​

Mobile

0–639px

Tablet

640–1023px

Laptop

1024–1439px

Desktop

1440px+

Ultrawide

1920px+

Layouts should adapt gracefully at every breakpoint.

Design Tokens ​

Every visual property should map to a design token.

Never hardcode colors, spacing, typography, radii, or shadows inside components.

Tokens are the single source of truth.

Implementation examples are defined later in this document.

Component Philosophy ​

Every component in MHMD Studio should be:

  • Reusable
  • Accessible
  • Responsive
  • Predictable
  • Composable
  • Easy to maintain

Components should solve one problem well.

Avoid creating components that combine unrelated responsibilities.

Whenever possible:

  • Extend existing components.
  • Reuse existing patterns.
  • Avoid one-off implementations.

Every component should exist within the design system before being used in production.

Component Hierarchy ​

The interface is built using the following hierarchy:

Design Tokens
    ↓
Primitive Components
    ↓
Composite Components
    ↓
Sections
    ↓
Pages

No page should bypass the component system.

Component Naming ​

Use consistent naming.

Examples:

Button
IconButton
Card
Input
Textarea
Select
Badge
Avatar
Modal
Dropdown
Navigation
Hero
FeatureCard
PortfolioCard
ArticleCard

Avoid names that describe appearance instead of function.

Example:

❌ BlueButton

✅ PrimaryButton

Buttons ​

Buttons communicate available actions.

There should be as few button variants as possible.

Primary Button ​

Purpose:

Primary action.

Characteristics:

  • Transparent background
  • 1px Primary border
  • Primary text
  • Rounded 8px
  • Compact padding
  • Arrow icon optional

Used for:

  • Contact
  • Get Started
  • View Project
  • Read Article

Secondary Button ​

Purpose:

Supporting actions.

Characteristics:

  • Transparent
  • Neutral border
  • Neutral text

Filled Button ​

Purpose:

High emphasis.

Characteristics:

  • Dark background
  • White text

Used sparingly.

Never fill buttons with the accent blue.

Ghost Button ​

Purpose:

Low emphasis.

Characteristics:

  • No border
  • No fill
  • Text only

Icon Button ​

Purpose:

Single-icon actions.

Requirements:

Minimum touch target:

44×44px

Keyboard focus required.

Accessible label required.

Button States ​

Every button supports:

Default

Hover

Active

Focus

Disabled

Loading

Success (optional)

Button Rules ​

Buttons should:

Clearly communicate clickability.

Never shift layout during loading.

Always display visible focus indicators.

Never rely only on color.

Navigation communicates structure.

It should remain calm and predictable.

Desktop Navigation ​

Floating pill.

Centered.

Glassmorphism allowed.

Contains:

  • Logo
  • Primary links
  • CTA

Mobile Navigation ​

Drawer.

Simple.

Keyboard accessible.

Focus trapped.

Escape closes.

Navigation should:

Remain consistent.

Never hide unexpectedly.

Avoid multiple navigation bars.

Clearly indicate current page.

Cards ​

Cards group related content.

Cards should never become generic containers.

Every card type has a defined purpose.

Content Card ​

Used for:

Text.

Resources.

Articles.

Portfolio Card ​

Used for:

Projects.

Preview image.

Short summary.

Metadata.

Feature Card ​

Used for:

Homepage features.

Capabilities.

Benefits.

Testimonial Card ​

Used only when genuine testimonials exist.

Avoid placeholders.

Diagram Card ​

Used for:

Illustrations.

Architecture diagrams.

System explanations.

Card Rules ​

Cards should:

Have one clear purpose.

Maintain consistent padding.

Never contain excessive nesting.

Avoid unnecessary shadows.

Inputs ​

Inputs prioritize readability.

Use subtle backgrounds.

Minimal borders.

Clear labels.

Accessible helper text.

Supported inputs:

  • Text
  • Email
  • Password
  • Number
  • Search
  • URL

Textarea ​

Auto-growing.

Character count optional.

Clear label required.

Select ​

Avoid custom selects unless necessary.

Native behavior preferred.

Checkbox ​

Always include:

Visible label.

Large hit area.

Keyboard support.

Radio Group ​

Use only when options are mutually exclusive.

Never more than seven options.

Toggle Switch ​

Reserved for:

Settings.

Preferences.

Enable/Disable actions.

Never use toggles for navigation.

Forms ​

Forms should feel effortless.

Only request necessary information.

Contact Form ​

Fields:

Name

Email

Company (optional)

Project Type

Budget (optional)

Message

Validation ​

Validation should:

Be immediate where appropriate.

Explain problems clearly.

Never blame users.

Display success visibly.

Form Layout ​

Single column preferred.

Labels above inputs.

Clear spacing.

Logical grouping.

Purpose:

Temporary focused tasks.

Rules:

Focus trap required.

Escape closes.

Overlay click configurable.

Avoid nested modals.

Drawer ​

Used primarily on mobile.

Slides from edge.

Never cover critical navigation permanently.

Keep options concise.

Maximum visible items:

10

Longer lists require search.

Tooltip ​

Purpose:

Clarification.

Not primary content.

Delay:

150–300ms.

Keyboard accessible.

Popover ​

Purpose:

Rich contextual information.

More complex than tooltips.

Should not replace pages.

Accordion ​

Purpose:

Progressive disclosure.

Only use when content naturally groups.

Avoid deeply nested accordions.

Tabs ​

Use for related content.

Maximum:

Five visible tabs.

Overflow requires alternate navigation.

Required for:

Portfolio projects.

Articles.

Documentation.

Never use on homepage.

Pagination ​

Use for:

Blog.

Portfolio.

Resources.

Never paginate short lists.

Search should support:

Articles.

Portfolio.

Resources.

Future documentation.

Results should update quickly.

Tables ​

Tables should:

Support responsive behavior.

Maintain alignment.

Use subtle dividers.

Avoid excessive borders.

Badges ​

Purpose:

Status.

Category.

Technology.

Metadata.

Never use badges as buttons.

Tags ​

Purpose:

Content classification.

Should remain clickable.

Consistent spacing required.

Alerts ​

Types:

Information

Success

Warning

Error

Requirements:

Icon.

Clear heading.

Action if applicable.

Toast Notifications ​

Reserved for:

Success.

Error.

Background operations.

Auto-dismiss where appropriate.

Never stack excessively.

Empty States ​

Every empty state should answer:

Why is this empty?

What can the user do next?

Should include:

Illustration (optional)

Short explanation

Action

Error States ​

Never display raw technical errors.

Instead provide:

Simple explanation.

Recovery action.

Support contact if necessary.

Loading States ​

Prefer skeleton loading over spinners.

Loading indicators should preserve layout.

Avoid blank screens.

Footer should feel editorial.

Contains:

Navigation

Contact

Social Links

Copyright

Short company statement

Newsletter (future)

Icons ​

Use one icon library consistently.

Preferred:

Lucide

Icons should:

Use consistent stroke width.

Align to pixel grid.

Remain secondary to typography.

Images ​

Prefer:

Illustrations.

Mockups.

Product visuals.

Avoid generic stock photography.

Every image should reinforce the brand.

Component Rules ​

Every component must:

Be reusable.

Be responsive.

Be accessible.

Be documented.

Support dark mode in the future.

Avoid unnecessary props.

Follow design tokens.

Never hardcode values.

AI Implementation Rules ​

When generating components, AI systems must:

Use existing components before creating new ones.

Respect design tokens.

Avoid duplicate functionality.

Maintain accessibility.

Document new components.

Avoid visual inconsistency.

Prefer composition over inheritance.

Never introduce unnecessary variants.

END OF PART 2 ​

The next section completes docs/10_design_system.md with:

  • Responsive behavior
  • Responsive layouts
  • Motion integration
  • Accessibility implementation
  • Interaction states
  • Micro-interactions
  • Iconography
  • Illustration system
  • Photography rules
  • Data visualization
  • Design QA checklist
  • Implementation standards
  • CSS architecture
  • Tailwind architecture
  • shadcn customization
  • Future evolution of the design system
  • Final implementation rules

Awaiting prompt: next for Design System - Part 3 (Final).

Responsive Design ​

Responsive design is a core requirement.

Layouts should adapt naturally across devices without hiding important functionality.

Every experience should feel intentionally designed rather than merely resized.

Breakpoints ​

DeviceWidth
Mobile0–639px
Tablet640–1023px
Laptop1024–1439px
Desktop1440–1919px
Ultrawide1920px+

Responsive Principles ​

Design mobile-first.

Scale upward.

Do not design desktop first and compress later.

Navigation, spacing, typography, and layout should be considered independently for each breakpoint.

Layout Rules ​

Desktop

  • 12-column grid
  • Maximum content width: 1200px
  • Reading width: 65–75 characters

Tablet

  • 8-column grid

Mobile

  • 4-column grid
  • Comfortable thumb interaction
  • Large touch targets

Responsive Typography ​

Typography should scale smoothly.

Avoid dramatic jumps between breakpoints.

Maintain hierarchy while improving readability.

Responsive Spacing ​

Increase spacing with larger screens.

Do not simply enlarge every element.

Whitespace should scale proportionally.

Responsive Images ​

Images should:

  • Use modern formats (AVIF, WebP)
  • Support responsive sizes
  • Lazy load by default
  • Preserve aspect ratios

Avoid downloading oversized assets.

Motion Integration ​

Motion exists to explain relationships.

Every animation must have purpose.

Allowed purposes include:

  • State change
  • Continuity
  • Hierarchy
  • Feedback
  • Focus
  • Navigation transitions

Remove animations that provide no informational value.

Motion Timing ​

Recommended durations:

TypeDuration
Hover120–180 ms
Button150–200 ms
Card180–240 ms
Modal250–350 ms
Page Transition300–500 ms

Avoid slow interfaces.

Easing ​

Preferred easing:

text
ease-out

ease-in-out

spring

Avoid:

  • Bounce
  • Elastic
  • Overshoot
  • Cartoon-like motion

Micro-Interactions ​

Use subtle interactions for:

  • Hover
  • Focus
  • Selection
  • Form validation
  • Navigation
  • Card elevation
  • Active states

Micro-interactions should feel natural rather than theatrical.

Page Transitions ​

Transitions should preserve context.

Users should understand where they came from and where they are going.

Avoid dramatic full-screen effects.

Scroll Behavior ​

Smooth scrolling is acceptable.

Avoid scroll hijacking.

Never prevent normal browser behavior.

Accessibility Implementation ​

Every interface must support:

  • Keyboard navigation
  • Screen readers
  • Focus visibility
  • Reduced motion
  • High contrast
  • Zoom up to 200%
  • Semantic HTML

Accessibility should never be deferred.

Focus States ​

Every interactive element requires a visible focus state.

Do not remove browser focus without replacing it with a better alternative.

Reduced Motion ​

Respect the user's operating system preference.

When reduced motion is enabled:

  • Remove unnecessary animations
  • Shorten transitions
  • Preserve usability

Color Contrast ​

Meet WCAG AA at minimum.

AAA should be used whenever practical.

Never rely solely on color to communicate meaning.

Iconography ​

Primary icon library:

Lucide

Icons should:

  • Match stroke width
  • Align to the pixel grid
  • Remain visually secondary
  • Never replace meaningful labels

Illustration Style ​

Illustrations should communicate atmosphere rather than information.

Preferred style:

  • Painterly
  • Editorial
  • Cinematic
  • Soft textures
  • Limited palette

Avoid:

  • Generic stock illustrations
  • Cartoon mascots
  • Overly abstract 3D graphics

Photography ​

Photography should be used sparingly.

Preferred subjects:

  • Products
  • Workspaces
  • Devices
  • Real projects

Avoid:

  • Generic office stock photos
  • Handshake imagery
  • Artificial business scenes

Data Visualization ​

Charts should:

  • Prioritize clarity
  • Use restrained color
  • Label directly when possible
  • Avoid decorative effects

Do not use 3D charts.

Empty Space ​

Whitespace is intentional.

Never fill space simply because it exists.

Allow layouts to breathe.

Visual Hierarchy ​

Hierarchy should primarily come from:

  1. Typography
  2. Layout
  3. Spacing
  4. Scale
  5. Motion
  6. Color

If hierarchy depends primarily on color, redesign the layout.

Design QA Checklist ​

Before approving any interface verify:

Visual ​

  • Typography follows scale
  • Consistent spacing
  • Correct colors
  • Correct border radius
  • Proper alignment
  • Balanced whitespace

UX ​

  • Clear primary action
  • Predictable navigation
  • No dead ends
  • Good readability
  • Minimal cognitive load

Accessibility ​

  • Keyboard support
  • Screen reader support
  • Focus states
  • Contrast
  • Reduced motion
  • Responsive behavior

Performance ​

  • Optimized images
  • Optimized fonts
  • Minimal JavaScript
  • Lazy loading
  • Responsive assets

CSS Architecture ​

Rules:

  • Use design tokens
  • Avoid magic numbers
  • Prefer utility-first styling
  • Avoid deeply nested selectors
  • Keep specificity low

Tailwind Guidelines ​

Use Tailwind v4.

Guidelines:

  • Utility-first
  • Reusable component classes
  • Minimal custom CSS
  • Design tokens mapped into Tailwind theme
  • Avoid arbitrary values whenever possible

shadcn/ui Customization ​

shadcn/ui serves as a foundation, not the finished design.

Every imported component should be adapted to:

  • Typography
  • Color palette
  • Spacing
  • Motion
  • Border radius
  • Accessibility
  • Brand identity

The final interface should not appear to use default shadcn styles.

Design System Maintenance ​

Whenever a new component is created:

  1. Determine whether an existing component can be reused.
  2. Update the design system documentation.
  3. Document variants.
  4. Document accessibility considerations.
  5. Document responsive behavior.

The design system should evolve deliberately.

Versioning ​

Major design changes require a version update.

Document:

  • What changed
  • Why it changed
  • Migration considerations
  • Affected components

Future Evolution ​

The design system should support future additions without breaking consistency.

Potential future expansions include:

  • Dark mode
  • Native applications
  • Dashboard UI
  • SaaS products
  • AI interfaces
  • Client portal
  • Mobile applications

The foundational principles should remain stable.

Final Rules ​

Every interface built under MHMD Studio should satisfy the following:

  • Purpose before decoration.
  • Consistency before novelty.
  • Accessibility before convenience.
  • Performance before complexity.
  • Systems before individual pages.
  • Documentation before implementation.
  • Quality before speed.

These rules are non-negotiable.

Related Documents

Design Principles
Read Documentation
Visual Language
Read Documentation
Motion Language
Read Documentation
Content Guidelines
Read Documentation
Components
Read Documentation
Technical Architecture
Read Documentation

End of Document ​

Designed & Built with precision.

© 2026 MHMD Studio. All rights reserved.