🚀 Etihad Design System
A comprehensive atomic design system built with SCSS and JavaScript for creating beautiful, scalable, and consistent user interfaces
Why Choose Our Design System?
Atomic Design
Organized into atoms, molecules, and organisms for maximum reusability and scalability
Learn More →Performance
Optimized CSS with minimal selector depth and efficient variable management
Optimize Now →Accessibility
WCAG 2.1 compliant with full keyboard navigation and screen reader support
View Standards →RTL/LTR Ready
Complete right-to-left and left-to-right language support with dedicated mixins
Explore RTL →What is Etihad Design System?
The Etihad Element Design System is a comprehensive, atomic design system built with SCSS and JavaScript. It provides a complete set of components and guidelines for creating beautiful, scalable, and consistent user interfaces across your applications.
Core Principles
- 🎯 Atomic Design: Components organized into atoms, molecules, and organisms for maximum modularity
- 🔄 Reusability: Each component is independent, composable, and fully reusable
- 🎨 Consistency: Unified styling across all components using CSS variables and centralized tokens
- 📈 Scalability: Easily extended to support new components, themes, and requirements
- ♿ Accessibility: WCAG 2.1 compliant with full keyboard navigation and screen reader support
- 📱 Responsive: Mobile-first approach with comprehensive breakpoint support
Quick Navigation
Quick Start Guide
1. Installation
npm install @etihad/element-design-system
2. Include CSS
<link rel="stylesheet" href="path/to/dist/css/index.min.css" />
3. Include JavaScript
<script src="path/to/dist/js/design-system-1.0.js"></script>
4. Start Building
Begin using design system components in your HTML with the ey- prefix:
<button class="ey-button ey-button__primary">Click Me</button>
💡 Tip: Use the design system with modern frameworks like React, Vue, or Angular for better component management and state handling.
Design System Architecture
Atomic Design Levels
Our design system follows the atomic design methodology, breaking down interfaces into hierarchical components:
Atoms
Basic building blocks that cannot be broken down further
Buttons, Inputs, Typography, Icons, Avatars
Molecules
Simple components made of atoms
Form Groups, Chips, Tabs, Alerts, Steppers
Organisms
Complex components made of molecules and atoms
Navigation, Footer, Modals, Cards, Tables
Naming Convention
All design system classes follow the ey- prefix with BEM naming convention:
ey-button // Block
ey-button__primary // Element
ey-button--large // Modifier
Project Structure
src/ ├── atoms/ │ ├── buttons/ │ ├── typography/ │ ├── avatar/ │ └── ... ├── molecules/ │ ├── form/ │ ├── chips/ │ ├── tabs/ │ └── ... ├── organisms/ │ ├── navigation-bar/ │ ├── modal/ │ ├── footer/ │ └── ... ├── template/ │ └── light/ │ ├── ey-common.scss (CSS variables) │ ├── ey-com.scss │ └── ey-content.scss ├── core/ │ ├── _mixins.scss │ ├── _functions.scss │ └── _variables.scss ├── reset.scss └── index.scss (main entry point)
src/index.scss is the main entry point that imports all
components in the correct order.
SCSS Guidelines & Best Practices
💾 CSS Variables (Custom Properties)
All color and spacing values should use CSS variables defined in src/template/light/ey-common.scss. This ensures consistency and makes theme switching simple:
.ey-button {
background-color: var(--ey-color-btn-primary);
color: var(--ey-color-btn-primary-text);
padding: var(--ey-space-16);
border-radius: var(--ey-border-radius);
transition: all var(--ey-transition-speed);
}
🔧 Mixins Usage
Common mixins defined in src/core/_mixins.scss help reduce code duplication and ensure consistency:
| Mixin | Purpose | Example |
|---|---|---|
@include breakpoint() |
Responsive breakpoints | @include breakpoint(sm-down) { ... } |
@include ey-direction() |
RTL/LTR support | @include ey-direction(margin, left, 16px); |
@include font-family() |
Font styling | @include font-family($var-font-medium); |
@include font-size() |
Typography sizing | @include font-size($var-body-size, $line-height); |
📱 Responsive Breakpoints
Our design system includes 5 responsive breakpoints for seamless mobile-first development:
⚠️ Important Rules
Creating Components
Component Structure
Each component should follow this file structure:
src/molecules/my-component/ ├── _my-component.scss (styles) ├── my-component.scss (exports) └── README.md (documentation)
Component Template
// src/molecules/my-component/_my-component.scss
.ey-my-component {
display: flex;
padding: var(--ey-space-16);
background-color: var(--ey-color-background);
@include breakpoint(sm-down) {
padding: var(--ey-space-12);
}
&__content {
flex: 1;
}
&--active {
background-color: var(--ey-color-primary);
}
}
Component Export
// src/molecules/my-component/my-component.scss
@import './my-component';
Component Registration
Add to src/index.scss:
@import "./molecules/my-component/my-component";
Best Practices
Styling Guidelines
- Always use CSS variables for colors and spacing
- Use the
ey-prefix for all classes - Follow BEM (Block Element Modifier) naming convention
- Avoid hard-coded values; use design tokens instead
- Support RTL/LTR with the
ey-directionmixin - Make components responsive using breakpoint mixins
- Use semantic HTML elements
- Ensure sufficient color contrast for accessibility
Code Organization
- Group related CSS properties together
- Nest selectors logically (max 3-4 levels deep)
- Use mixins for DRY (Don't Repeat Yourself) principles
- Document complex or non-obvious CSS rules with comments
- Keep component files focused and manageable (< 300 lines)
Performance Optimization
CSS Performance
- Minimize CSS selectors depth (max 3-4 levels)
- Avoid expensive pseudo-selectors like :not()
- Use
will-changesparingly for animations - Defer non-critical CSS loading
- Use CSS variables instead of preprocessor variables for runtime changes
Build Process
The design system uses Gulp for building. Key tasks:
npm run build # Build all assets
npm run watch # Watch for changes
npm run build:scss # Compile SCSS
npm run build:js # Compile JavaScript
Testing & Quality Assurance
Visual Testing
- Test components across all breakpoints (xs, sm, md, lg, xl)
- Verify RTL/LTR rendering
- Test with light and dark themes
- Validate color contrast ratios (WCAG AA minimum)
- Test on real devices, not just browsers
Accessibility Testing
- Ensure keyboard navigation works properly
- Use semantic HTML elements
- Add ARIA labels where necessary
- Test with screen readers
- Verify focus indicators are visible
Cross-browser Testing
| Browser | Minimum Version | Status |
|---|---|---|
| Chrome | 90+ | Supported |
| Firefox | 88+ | Supported |
| Safari | 14+ | Supported |
| Edge | 90+ | Supported |
Troubleshooting
Common Issues
CSS Variables Not Working
Issue: CSS custom properties appear as fallback values
// ❌ Wrong
background-color: var(--ey-color-primary, blue);
// ✓ Correct
background-color: var(--ey-color-btn-primary);
RTL Issues
Issue: Layout breaks in RTL mode
// ❌ Wrong
margin-left: 16px;
// ✓ Correct
@include ey-direction(margin, left, 16px);
Responsive Design Issues
Issue: Breakpoints not working as expected
// ❌ Wrong
@media (max-width: 600px) { ... }
// ✓ Correct
@include breakpoint(sm-down) { ... }
Debugging Tips
- Check browser DevTools for CSS specificity issues
- Verify CSS variables are defined in ey-common.scss
- Use source maps to trace compiled CSS back to SCSS
- Test with CSS variable polyfill for older browsers
- Clear browser cache when testing style changes
Resources & Support
📚 Component Library
Browse and explore all design system components with interactive examples
📐 Grid & Layout
Master responsive design with our comprehensive grid system
📝 Release Notes
Stay updated with the latest features and improvements
🔗 GitHub Repository
View source code, report issues, and contribute
Ready to Build?
Start using the Etihad Design System in your next project