ethio-telecom-typography-kit

v1.0.7

Published

7 days ago

Official responsive typography system and design tokens for Ethio Telecom digital products.

Downloads

612

0High
0Medium
0Low

yonas2754

ethio-telecom typography design-system design-tokens responsive-typography amharic ethiopic multilingual-ui css-typography

Ethio Telecom Typography Kit

The Ethio Telecom Typography Kit is a high-performance, fluid typography system that enforces a consistent typographic identity

It is purpose-built to solve a critical challenge in Ethiopian digital experiences: accurate vertical rhythm and glyph safety for Amharic (Ethiopic) scripts, while maintaining clean, dense, and responsive typography for English and other Latin-based languages.

🏛 Design Principles

1. Fluid by Default

All font sizes scale using CSS clamp() — eliminating fixed breakpoints and ensuring optimal readability from 320px mobile screens to 4K displays.

2. Multilingual Intelligence

The engine is script-aware and automatically adjusts line height when Amharic is detected, preventing glyph clipping and preserving accessibility.

Detection works via:

lang="am" attribute
.eth-amharic utility class
Nested Amharic contexts

3. Semantic-First Architecture

Typography is defined by semantic role, not pixel size. This ensures long-term consistency, faster development, and predictable UI behavior.

📐 Full Semantic Class Reference

The typography system is semantic-first. Classes are named by role and intent, not fixed size. All font sizes scale fluidly between mobile (320px) and desktop (1280px+) using CSS clamp().

| Class Name | Mobile → Desktop | Weight | LH (EN / AM) | Role | | -------------------------- | ---------------- | ------- | ------------- | -------------------------------- | | .eth-text-display | 48px → 72px | 700 | 1.1 / 1.4 | Large landing page headlines | | .eth-text-hero | 32px → 48px | 700 | 1.2 / 1.5 | Marketing & hero banners | | .eth-text-title-lg | 28px → 36px | 600 | 1.3 / 1.6 | Primary page headers | | .eth-text-title | 24px → 32px | 600 | 1.3 / 1.6 | Section titles | | .eth-text-heading | 18px → 22px | 600 | 1.4 / 1.6 | Card & module headers | | .eth-text-heading-sm | 16px → 18px | 600 | 1.4 / 1.6 | Compact UI headers & labels | | .eth-text-subtitle-lg | 16px → 18px | 400 | 1.5 / 1.7 | Lead paragraphs | | .eth-text-subtitle-md | 14px → 16px | 600 | 1.4 / 1.6 | Emphasized sub-labels | | .eth-text-body-lg | 15px → 16px | 400 | 1.5 / 1.8 | Primary reading content | | .eth-text-body-md | 13px → 14px | 400 | 1.5 / 1.7 | Standard UI text (default) | | .eth-text-body-sm | 11px → 12px | 400 | 1.4 / 1.6 | Metadata & captions |

🚀 Installation

# npm
npm install ethio-telecom-typography-kit

# yarn
yarn add ethio-telecom-typography-kit

🔌 Integration

Next.js

Import the compiled CSS once at the application root.

import 'ethio-telecom-typography-kit/dist/ethio-telecom-typography.css';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className="eth-text-body-md">
        {children}
      </body>
    </html>
  );
}

Standard React (Vite / CRA)

import 'ethio-telecom-typography-kit/dist/ethio-telecom-typography.css';
import App from './App';

ReactDOM.createRoot(
  document.getElementById('root')!
).render(<App />);

🌍 Multilingual Usage

The typography engine adapts automatically based on the detected script.

// English (Latin script)
<p className="eth-text-body-md">
  Your balance is 50 ETB.
</p>

// Amharic (Ethiopic script)
<p className="eth-text-body-md" lang="am">
  ቀሪ ሂሳብዎ 50 ብር ነው።
</p>

💡 Best Practices

**Use .eth-text-display** for landing page "Wow" factors.
**Use .eth-text-title-lg** for primary SharePoint page headings.
**Always set lang="am"** when the text is in Amharic to activate the 1.6 - 1.8 line-heights.

⌨️ Design Tokens (Developer API)

For advanced use cases (Tailwind CSS, CSS-in-JS, Material UI, custom engines), the kit exports TypeScript Design Tokens.

Design Tokens are the single source of truth. SCSS mixins and compiled CSS utilities are generated from these values to guarantee consistency.

Token Reference Table

| Category | Token Name | Description | | --------------------------- | ------------------ | ---------------------------------------------------------------------------- | | Font Family | family.base | Primary font stack with Ethiopic fallback (Segoe UI, Noto Sans Ethiopic) | | Font Weights | weights.regular | Regular text weight (400) | | | weights.semibold | Emphasized and structural text (600) | | | weights.bold | High-impact display and hero text (700) | | Font Sizes | sizes.display | Extra-large display typography (landing pages, hero sections) | | | sizes.hero | Hero banners and marketing headlines | | | sizes.titleLg | Primary page titles | | | sizes.title | Section and content titles | | | sizes.heading | Card and module headings | | | sizes.headingSm | Compact UI headings and labels | | | sizes.subtitleLg | Lead paragraphs and emphasized descriptions | | | sizes.subtitleMd | Secondary subtitles and bold sub-labels | | | sizes.bodyLg | Main reading content | | | sizes.bodyMd | Default UI body text | | | sizes.bodySm | Metadata, helper text, and captions | | Line Heights (Latin) | lineHeights.en.* | Optimized line heights for English and Latin scripts | | Line Heights (Ethiopic) | lineHeights.am.* | Expanded line heights for Amharic to prevent glyph clipping |

Token Usage Example

import { EthTypographyTokens } from 'ethio-telecom-typography-kit';

const style = {
  fontFamily: EthTypographyTokens.family.base,
  fontSize: EthTypographyTokens.sizes.heading,
  fontWeight: EthTypographyTokens.weights.semibold,
  lineHeight: EthTypographyTokens.lineHeights.am.heading,
};

🎨 Weight Usage Guidelines

Bold (700): High-impact hero and promotional messaging
Semibold (600): Navigation, labels, and structural hierarchy
Regular (400): Body content and informational text

📄 License & Ownership

This package is strictly intended for internal use. Unauthorized distribution outside Ethio Telecom is prohibited.

Principal Author Yonas In-House Solution Development Specialist, Ethio Telecom