Components

This document is the implementation specification for every reusable UI component within MHMD Studio. It defines component responsibilities, APIs, variants, accessibility requirements, implementation standards, testing requirements, and composition rules. Every interface must be assembled from these components whenever possible.

Document Metadata

Property	Value
Document	Components
Version	1.0
Status	Active
Owner	Mohammed El Maachi
Last Updated	July 2026

Purpose

This document defines the reusable component library used throughout MHMD Studio.

Its objectives are:

Eliminate duplicate UI.
Increase development speed.
Improve consistency.
Reduce maintenance costs.
Standardize accessibility.
Simplify future expansion.

Every component must exist in this document before production use.

Component Philosophy

Components should be:

Reusable
Predictable
Accessible
Composable
Minimal
Well documented

A component should solve one responsibility exceptionally well.

Avoid "Swiss Army knife" components that attempt to solve unrelated problems.

Component Hierarchy

text

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

Pages should never bypass the component hierarchy.

Component Categories

The library is divided into:

Foundations
Navigation
Actions
Inputs
Data Display
Feedback
Layout
Content
Media
Utilities

Foundations

Foundation components should rarely be used directly by pages.

Examples:

Container
Stack
Grid
Divider
Spacer
Surface

These become building blocks for larger components.

Container

Purpose

Constrain content width and establish consistent page alignment.

Variants

Default
Narrow
Wide
Full Width

Responsibilities

Horizontal padding
Max width
Responsive behavior

Accessibility

No accessibility requirements beyond semantic usage.

Stack

Purpose

Create consistent vertical spacing.

Avoid manually adding margins between elements.

Properties

Gap
Alignment
Direction

Rules

Always prefer Stack over manual spacing.

Grid

Purpose

Create responsive layouts.

Supported Columns

Rules

Layouts should collapse gracefully on smaller screens.

Divider

Purpose:

Separate related content.

Variants:

Horizontal
Vertical

Keep visual weight subtle.

Spacer

Purpose:

Create intentional empty space.

Avoid arbitrary margin utilities when a Spacer component improves consistency.

Surface

Purpose:

Provide consistent visual containers.

Variants:

Default
Elevated
Glass
Outline

Includes:

NavigationBar
NavigationLink
NavigationGroup
MobileMenu
Breadcrumb
FooterNavigation

NavigationBar

Responsibilities

Display logo
Primary navigation
Primary CTA
Mobile navigation trigger

States

Default
Scrolled
Mobile
Expanded

Accessibility

Keyboard navigation
Landmark role
Skip link compatibility
Visible focus

NavigationLink

Variants:

Default
Active
Disabled

MobileMenu

Requirements:

Focus trap
Escape closes
Scroll lock
Accessible labels

Purpose:

Communicate hierarchy.

Should be automatically generated where possible.

FooterNavigation

Contains:

Company
Resources
Legal
Social

Should remain data-driven.

Action Components

Includes:

Button
IconButton
LinkButton
FloatingActionButton (future)

Button

Variants

Primary
Secondary
Filled
Ghost
Destructive

Sizes

Small
Medium
Large

States

Default
Hover
Active
Focus
Disabled
Loading

Properties

Variant
Size
Icon
Icon Position
Full Width
Loading
Disabled

Accessibility

Minimum touch target:

44 × 44 px

Visible focus state.

Accessible loading state.

IconButton

Purpose:

Compact icon-only actions.

Requirements:

aria-label mandatory
Consistent sizing
Keyboard support

LinkButton

Purpose:

Navigation styled as a button.

Should preserve proper semantic links.

Input Components

Includes:

Input
Textarea
Select
Checkbox
Radio
Toggle
SearchInput

Input

Supported Types:

Text
Email
Password
URL
Search
Number
Telephone

Features

Label
Placeholder
Helper text
Error state
Disabled state

Accessibility

Associated label required.

Error announced.

Focus visible.

Autocomplete supported where applicable.

Textarea

Features:

Auto resize
Character count (optional)
Validation

Select

Requirements:

Keyboard support
Screen reader compatibility
Search support (future)

Checkbox

Requirements:

Large click target
Visible label
Keyboard support

Radio Group

Rules:

Use only when one option must be selected.

Toggle

Purpose:

Binary settings.

Should never replace navigation.

SearchInput

Future capabilities:

Suggestions
Recent searches
Keyboard shortcuts

Component Naming

Use PascalCase.

Examples:

text

Button

NavigationBar

PortfolioCard

ArticleCard

CaseStudyHero

ContactForm

NewsletterSignup

Avoid ambiguous names.

Component names should describe purpose rather than appearance.

Documentation Requirements

Every component must include:

Purpose
Props
Variants
States
Accessibility
Responsive behavior
Usage examples
Testing requirements
Related components

Data Display Components

Data display components communicate structured information.

They should prioritize readability and hierarchy over decoration.

Card

Purpose

Display a single piece of related information.

Cards are the primary content container throughout MHMD Studio.

Variants

Default
Outline
Elevated
Glass (restricted use)
Interactive

Properties

Title
Description
Thumbnail (optional)
Footer (optional)
Actions (optional)

Rules

One primary purpose per card.
Avoid nested cards whenever possible.
Maintain consistent padding.

PortfolioCard

Purpose

Preview a portfolio project.

Required Content

Project Thumbnail
Project Title
Short Description
Categories
Technologies
Year

Interaction

Hover should communicate clickability without distracting animation.

CaseStudyCard

Displays a featured case study.

Includes:

Hero Image
Project Summary
Primary Outcome
CTA

ServiceCard

Displays a service offering.

Required:

Icon or Illustration
Title
Summary
Learn More CTA

ArticleCard

Displays blog content.

Required:

Cover Image
Category
Reading Time
Title
Summary
Publish Date

ResourceCard

Displays downloadable resources.

Required:

Resource Type
Thumbnail
Description
Download Action

TeamCard (Future)

Purpose:

Display team members.

Required:

Photo
Name
Role
Biography
Social Links (optional)

TestimonialCard

Only use verified testimonials.

Required:

Name
Position
Company
Quote

Never use placeholder testimonials.

StatisticsCard

Purpose:

Display key metrics.

Should include:

Number
Label
Supporting Context

Avoid animated counters unless they improve understanding.

Timeline

Purpose:

Present chronological information.

Use for:

Process
Company History
Case Studies
Roadmaps

Accordion

Purpose:

Reveal secondary information.

Common uses:

FAQ
Technical Details
Documentation

Tabs

Purpose:

Switch between related content.

Maximum visible tabs:

Five

More options require another navigation pattern.

Table

Purpose:

Display structured datasets.

Requirements:

Responsive
Accessible
Sortable (where appropriate)

Avoid horizontal scrolling unless unavoidable.

CodeBlock

Purpose:

Present source code.

Requirements:

Syntax highlighting
Copy button
Line numbers (optional)

Long code examples should support horizontal scrolling.

Quote

Purpose:

Highlight important statements.

Variants:

Standard
Editorial
Pull Quote

Use sparingly.

Figure

Purpose:

Associate images with explanatory text.

Every figure should include:

Image
Caption
Optional attribution

Feedback Components

Includes:

Alert
Toast
Banner
EmptyState
ErrorState
LoadingState

Alert

Variants:

Information
Success
Warning
Error

Should contain:

Icon
Heading
Description
Action (optional)

Toast

Purpose:

Temporary feedback.

Should:

Auto-dismiss
Support keyboard users
Avoid stacking excessively

Purpose:

Persistent information.

Examples:

Maintenance
Product Updates
Cookie Notice

EmptyState

Should answer:

Why is this empty?
What can the user do next?

Include:

Illustration (optional)
Message
Primary Action

ErrorState

Should include:

Clear explanation
Recovery action
Optional support contact

Never expose internal errors.

LoadingState

Preferred:

Skeletons

Fallback:

Spinner

Maintain layout stability.

Media Components

Includes:

Image
Video
Gallery
Carousel
Lightbox

Image

Requirements:

Responsive
Lazy loaded
Optimized
Descriptive alt text

Video

Support:

Captions
Keyboard controls
Responsive sizing

Avoid autoplay with sound.

Gallery

Purpose:

Present multiple related images.

Support:

Keyboard navigation
Swipe
Lightbox integration

Carousel

Use sparingly.

Requirements:

Manual navigation
Keyboard support
Swipe support
Visible controls

Do not autoplay.

Purpose:

View media in detail.

Requirements:

Escape closes
Focus trap
Zoom support
Keyboard navigation

Layout Components

Includes:

Section
Hero
FeatureGrid
ContentGrid
Sidebar
CTASection

Section

Provides:

Consistent spacing
Width constraints
Responsive behavior

Every page should primarily consist of reusable Section components.

Hero

Supports:

Heading
Subheading
CTA
Illustration
Background Media

Only one Hero per page.

FeatureGrid

Displays:

Features
Services
Benefits

Supports responsive column layouts.

CTASection

Purpose:

Encourage a meaningful next step.

Should contain:

Heading
Supporting copy
Primary CTA
Optional secondary CTA

Avoid multiple competing actions.

Form Components

Includes:

ContactForm
NewsletterForm
SearchForm

Every form should share validation behavior and visual consistency.

Component Composition

Components should compose naturally.

Example:

text

Page

↓

Section

↓

Container

↓

FeatureGrid

↓

ServiceCard

Avoid deeply nested hierarchies.

Responsive Requirements

Every component must support:

Mobile
Tablet
Laptop
Desktop

Components should not require separate implementations for each device.

Performance Requirements

Components should:

Avoid unnecessary re-renders.
Minimize bundle size.
Lazy load heavy assets.
Support code splitting when appropriate.

Accessibility Requirements

Every interactive component must support:

Keyboard navigation
Screen readers
Focus management
Sufficient contrast
Reduced motion preferences

Accessibility is mandatory.

Testing Requirements

Each component should have:

Unit tests
Accessibility tests
Visual regression tests
Interaction tests

Critical components should include end-to-end tests.

Documentation Requirements

Every component should include:

Description
Props
Variants
Examples
Accessibility notes
Responsive behavior
Performance considerations

Documentation should remain synchronized with implementation.

Storybook

Every reusable component should have a Storybook story.

Stories should include:

Default state
Variants
Edge cases
Accessibility examples
Responsive examples

Storybook becomes the visual reference for the component library.

AI Implementation Rules

AI systems creating components must:

Search for existing components before creating new ones.
Reuse established APIs.
Follow naming conventions.
Respect design tokens.
Preserve accessibility.
Avoid unnecessary variants.
Update documentation whenever components change.

Creating duplicate components is considered an implementation error.

Final Principle

The strength of the interface comes from the quality of its reusable components rather than the uniqueness of individual pages.

Every new component should improve the system as a whole.

Components ​

Document Metadata ​

Purpose ​

Component Philosophy ​

Component Hierarchy ​

Component Categories ​

Foundations ​

Container ​

Purpose ​

Variants ​

Responsibilities ​

Accessibility ​

Stack ​

Purpose ​

Properties ​

Rules ​

Grid ​

Purpose ​

Supported Columns ​

Rules ​

Divider ​

Spacer ​

Surface ​

Navigation Components ​

NavigationBar ​

Responsibilities ​

States ​

Accessibility ​

NavigationLink ​

MobileMenu ​

Breadcrumb ​

FooterNavigation ​

Action Components ​

Button ​

Variants ​

Sizes ​

States ​

Properties ​

Accessibility ​

IconButton ​

LinkButton ​

Input Components ​

Input ​

Features ​

Accessibility ​

Textarea ​

Select ​

Checkbox ​

Radio Group ​

Toggle ​

SearchInput ​

Component Naming ​

Documentation Requirements ​

Related Documents

Data Display Components ​

Card ​

Purpose ​

Variants ​

Properties ​

Rules ​

PortfolioCard ​

Purpose ​

Required Content ​

Interaction ​

CaseStudyCard ​

ServiceCard ​

ArticleCard ​

ResourceCard ​

TeamCard (Future) ​

TestimonialCard ​

StatisticsCard ​

Timeline ​

Accordion ​

Tabs ​

Table ​

CodeBlock ​

Quote ​

Figure ​

Feedback Components ​

Alert ​

Components

Document Metadata

Purpose

Component Philosophy

Component Hierarchy

Component Categories

Foundations

Container

Purpose

Variants

Responsibilities

Accessibility

Stack

Purpose

Properties

Rules

Grid

Purpose

Supported Columns

Rules

Divider

Spacer

Surface

Navigation Components

NavigationBar

Responsibilities

States

Accessibility

NavigationLink

MobileMenu

Breadcrumb

FooterNavigation

Action Components

Button

Variants

Sizes

States

Properties

Accessibility

IconButton

LinkButton

Input Components

Input

Features

Accessibility

Textarea

Select

Checkbox

Radio Group

Toggle

SearchInput

Component Naming

Documentation Requirements

Data Display Components

Card

Purpose

Variants

Properties

Rules

PortfolioCard

Purpose

Required Content

Interaction

CaseStudyCard

ServiceCard

ArticleCard

ResourceCard

TeamCard (Future)

TestimonialCard

StatisticsCard

Timeline

Accordion

Tabs

Table

CodeBlock

Quote

Figure

Feedback Components

Alert

Toast