Telegram Web DESIGN.md

The official design system for building Telegram's web product UI. Rooted in clarity, speed, and privacy-first interaction — a minimal but expressive communication platform.

Design Philosophy: Clean, fast, and frictionless. Telegram's UI prioritizes content over chrome. Every component is lightweight, responsive, and optimized for cross-platform consistency. The interface stays out of the user's way.

1. Color Palette

Primary Brand Colors

Light Mode Colors

Dark Mode Colors

Message Bubble Colors

Status & Semantic Colors

Data Visualization Colors

2. Typography

Font Stacks

css/* Primary — System San-Serif */
--tg-font-primary: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
                   Helvetica, Arial, sans-serif,
                   "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";

/* Legacy / Alternate */
--tg-font-legacy: "Lucida Grande", "Lucida Sans Unicode",
                  Arial, Helvetica, Verdana, sans-serif;

/* Light / Display (landing headings) */
--tg-font-light: "HelveticaNeue-Light", "Helvetica Neue Light",
                 "Helvetica Light", Helvetica, Arial, Verdana, sans-serif;

/* Monospace (code, technical content) */
--tg-font-mono: Monaco, Menlo, Consolas, "Courier New", monospace;

Type Scale

Font Weights

Typography Guidelines

• Line length: Max 800px content width for readable prose; 65ch for long-form articles
• Alignment: Left-aligned text as default; center only for hero headlines and short taglines
• Letter spacing: -1px to -2px for large display headings; default tracking for body
• Hierarchy: Weight and size define hierarchy — color used sparingly for emphasis
• RTL support: Full right-to-left (direction: rtl) support for Arabic, Persian, Hebrew
• Code: Always use --tg-font-mono for API references, code snippets, and technical strings

3. Spacing & Layout

Base Spacing Scale

Content Width Containers

Breakpoints

Layout Grid

• 4px baseline grid: All spacing and sizing aligns to 4px increments
• Flexible columns: CSS Grid or Flexbox for responsive layouts
• Mobile-first: Progressive enhancement from 320px baseline
• Navigation offset: Content starts at margin-top: 50px to clear fixed navbar

4. Borders & Shadows

Border Width

Border Radius

Shadows

Focus States

css--tg-focus-color: #2481CC;
--tg-focus-width: 2px;
--tg-focus-style: solid;

5. Iconography

Icon System

Telegram uses a custom SVG icon set designed for the messaging and product interface. No public icon library name — icons are internally maintained and rendered inline or via CSS background-image.

Icon Sizes

Icon Categories

Key UI Icons

send            — Paper plane (outgoing message)
verified        — Blue circle with white checkmark
double-check    — Two checkmarks (message read)
single-check    — One checkmark (message delivered)
mute            — Bell with slash
pin             — Pushpin
forward         — Curved arrow right
reply           — Curved arrow left
menu-dots       — Three dots horizontal (more actions)
search          — Magnifying glass
close           — × mark
back            — ← chevron
premium-star    — Star shape (Telegram Stars / Premium)

Icon Guidelines

• Stroke width: 1–1.5px for small icons; filled for status indicators
• Color: Inherits from parent, or uses --tg-color-brand for branded icons
• Verification badge: Always rendered in Telegram Blue (#1C93E3) with white fill
• Accessibility: Pair all icons with text labels or aria-label attributes

6. Component Patterns

Buttons

Button Variants

Button Sizes

Button States

css/* Platform Download Button */
--tg-btn-download-rest:   #A19481;
--tg-btn-download-hover:  #A99D8B;
--tg-btn-download-active: #998E7E;

/* Primary Brand Button */
--tg-btn-primary-rest:    #318FD3;
--tg-btn-primary-hover:   #2481CC;
--tg-btn-primary-active:  #1A6AAE;

/* Nav Link */
--tg-btn-nav-rest:        transparent;
--tg-btn-nav-hover:       #F0F6FA;
--tg-btn-nav-active-bg:   #1E98D4;
--tg-btn-nav-active-text: #FFFFFF;

Navigation

css/* Fixed top navbar */
position: fixed;
top: 0;
left: 0;
right: 0;
background: #FFFFFF;         /* or rgba(255,255,255,0.84) + backdrop-filter */
border-bottom: 1px solid #E8E8E8;
height: 50px;

/* Active nav indicator underline */
height: 3px;
background: #179CDE;
border-radius: 2px 2px 0 0;
bottom: -1px;
transition: opacity 0.2s ease-in-out, transform 0.2s ease-in-out;
transform-origin: bottom;
transform: scaleX(0.3) scaleY(0);   /* resting */
/* → scaleX(1) scaleY(1) on hover/active */

Form Controls

Text Input

Dropdown Menu

cssmin-width: 177px;
padding: 0;
background-color: #FFFFFF;
border: 1px solid rgba(29, 92, 123, 0.3);
box-shadow: 0 1px 1px rgba(20, 60, 83, 0.1);

/* Item */
padding: 8px 18px;
font-size: 13px;
color: #0088CC;

/* Item Hover */
background-color: #1E98D4;
color: #FFFFFF;

Message Bubbles

css/* Incoming message */
background: #FFFFFF;
border-radius: 0 12px 12px 12px;
padding: 8px 12px;
max-width: 320px;

/* Outgoing message */
background: #EFFDDE;
border-radius: 12px 0 12px 12px;
padding: 8px 12px;
max-width: 320px;
margin-left: auto;

/* Timestamp inside bubble */
font-size: 11px;
color: #A0ADB5;
float: right;
margin-top: 4px;
margin-left: 8px;

Cards (Feature Cards)

css/* telegram.org feature card */
max-width: 260px;
margin: 0 auto;
padding: 20px 0 9px;
text-align: center;

/* Card image */
width: 160px;
height: 160px;
margin: 0 auto;

/* Card header */
color: #A19679;         /* neutral variant */
/* or */
color: #0088CC;         /* brand variant */
font-size: 26px;
font-weight: normal;
letter-spacing: -1px;
margin: 15px 0 6px;

/* Card lead */
font-size: 15px;
line-height: 158%;
text-align: center;

Code Blocks

css/* Code block container */
background: #ECF3F8;
color: #546172;
border-radius: 4px;
padding: 9.5px;
font-family: Monaco, Menlo, Consolas, "Courier New", monospace;
font-size: 13px;
line-height: 20px;
overflow-x: auto;

/* Inline code */
background: #FEE AE4;
color: #C61717;
padding: 3px 5px;
border-radius: 0;

/* Blockquote */
border-left: 4px solid #179CDE;
padding: 5px 17px;
color: inherit;

Avatars

Badges & Labels

7. Motion & Animation

Duration Tokens

Easing Functions

css--tg-ease-in-out: ease-in-out;
--tg-ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
--tg-ease-out: cubic-bezier(0, 0, 0.2, 1);
--tg-ease-in: cubic-bezier(0.4, 0, 1, 1);

Animation Patterns

Nav Underline Transition

css/* Resting */
opacity: 0;
transform: scaleX(0.3) scaleY(0);
transform-origin: bottom;

/* Active / Hover */
opacity: 1;
transform: scaleX(1) scaleY(1);
transition: opacity 0.2s ease-in-out, transform 0.2s ease-in-out;

Logo Animation

css/* Telegram sprite-based logo animation */
animation: t-logo-play 500ms steps(30) both;
background-size: cover;

@keyframes t-logo-play {
  from { background-position: 0% 0%; }
  to   { background-position: 100% 0%; }
}

Reduced Motion

css@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

8. Accessibility Standards

Color Contrast Requirements

Focus States

• All interactive elements must show visible focus indicators
• Focus outline: 2px solid #2481CC
• Never suppress :focus-visible without providing a visible alternative
• Nav links: focus background #F0F6FA

Keyboard Navigation

ARIA Patterns

html<!-- Nav with active state -->
<nav role="navigation" aria-label="Main navigation">
  <a href="/" aria-current="page">Home</a>
</nav>

<!-- Loading state button -->
<button aria-busy="true" aria-live="polite">
  <span class="sr-only">Loading...</span>
  Sending
</button>

<!-- Icon-only action -->
<button aria-label="Send message">
  <svg aria-hidden="true">...</svg>
</button>

<!-- Verified badge -->
<span role="img" aria-label="Verified account">
  <svg aria-hidden="true">...</svg>
</span>

Screen Reader Considerations

• Use semantic HTML (<nav>, <main>, <article>, <section>, <footer>)
• Provide text alternatives for all platform/status icons
• Announce message delivery state changes (aria-live="polite")
• Maintain a logical heading hierarchy: h1 → h2 → h3
• Label all form inputs with visible <label> or aria-label
• RTL content: set dir="rtl" on container elements for Arabic/Persian/Hebrew

9. Platform-Specific Guidelines

Web Application Layout Structure

┌──────────────────────────────────────────────────────────────┐
│ Navbar (fixed, 50px height, white + bottom border)           │
│  Logo | Nav Links | Language Selector | [Sign In]            │
├────────────────┬─────────────────────────────────────────────┤
│                │                                             │
│  Sidebar Nav   │   Main Content Area                        │
│  (dev docs)    │   max-width: 800px, margin: 0 auto         │
│                │                                             │
│                │  ┌─────────────────────────────────────┐   │
│                │  │ Page / Hero Section                 │   │
│                │  ├─────────────────────────────────────┤   │
│                │  │ Content (cards, text, API docs)     │   │
│                │  └─────────────────────────────────────┘   │
│                │                                             │
└────────────────┴─────────────────────────────────────────────┘
│ Footer (max-width: 925px, flex row, border-top: #E8E8E8)     │
└──────────────────────────────────────────────────────────────┘

Landing Page Pattern (telegram.org)

Navbar (fixed)
  ├── Logo (128×128 animated)
  ├── App Title (34px, letter-spacing: -2px)
  ├── Tagline (20px, light weight, muted color)
  └── Download Buttons (platform-specific)

Feature Card Grid (max-width: 950px)
  ├── 1-col mobile → 2-col @768px → 3-col @992px
  ├── 160×160px animated GIF illustrations
  └── Card header + short lead text

Blog / Recent News Section
  ├── 2-col card grid (50% each, max-width: 800px)
  ├── Card: image + title + lead + date
  └── Single-column below 640px

Footer (flex row, 5 columns, max-width: 925px)

Developer Documentation Pattern

Sidebar Nav (right-positioned, 200px)
  ├── position: absolute → fixed (affix on scroll)
  ├── Active item: border-left: 2px solid #179CDE
  └── Nested items: smaller font, indent

Content Area (max-width: 800px)
  ├── Breadcrumb
  ├── Page title
  ├── Rich markdown content
  │    ├── Code blocks (ECF3F8 bg, 546172 text)
  │    ├── Inline code (FEEAE4 bg, C61717 text)
  │    └── Blockquotes (left border: 4px #179CDE)
  └── Edit form (for maintainers)

Overlay / Dialog Sizes

Markdown Rendering

Heading Styles

Block Elements

css/* Blockquote */
border-left: 4px solid #179CDE;
padding: 5px 17px;
font-size: 14px;
line-height: 20px;

/* Inline code */
background: #FEEAE4;
color: #C61717;
padding: 3px 5px;

/* Code block */
background: #ECF3F8;
color: #546172;
font-size: 13px;
line-height: 20px;
overflow-x: auto;

/* Table cell */
border: 1px solid #D5D5D5;

/* Horizontal rule */
border-top: 1px solid #E8E8E8;
margin: 24px 0;

Quick Reference

Essential CSS Variables

css/* Brand */
--tg-color-brand:      #26A5E4;
--tg-color-accent:     #2481CC;
--tg-color-highlight:  #179CDE;
--tg-link-color:       #0088CC;

/* Light mode surfaces */
--tg-bg-default:       #FFFFFF;
--tg-bg-muted:         #F7F7F7;
--tg-bg-surface:       #ECF3F8;
--tg-bg-accent-tint:   #E5F1FA;

/* Dark mode surfaces */
--tg-bg-dark-default:  #000000;
--tg-bg-dark-surface:  #1E1E1E;
--tg-bg-dark-muted:    #212429;

/* Text */
--tg-text-default:     #000000;
--tg-text-muted:       #7D7F81;
--tg-text-secondary:   #808080;

/* Borders */
--tg-border-default:   #E6E6E6;
--tg-border-subtle:    #E8E8E8;

/* Typography */
--tg-font-primary: -apple-system, BlinkMacSystemFont, "Segoe UI",
                   Roboto, Helvetica, Arial, sans-serif;
--tg-font-mono:    Monaco, Menlo, Consolas, "Courier New", monospace;

/* Spacing */
--tg-space-8:  0.5rem;
--tg-space-16: 1rem;
--tg-space-24: 1.5rem;

/* Radius */
--tg-radius-medium: 4px;
--tg-radius-full:   50%;
--tg-radius-pill:   16px;

/* Focus */
--tg-focus-color:  #2481CC;
--tg-focus-width:  2px;

Resources

• Telegram Web: https://web.telegram.org
• Telegram Homepage: https://telegram.org
• Developer Docs: https://core.telegram.org
• Bot API: https://core.telegram.org/bots/api
• App Downloads: https://telegram.org/apps
• Brand Assets: https://telegram.org/tour/screenshots

Based on Telegram's publicly observable web design patterns, telegram.org CSS, and official brand color references. For the most current specifications, refer to telegram.org and core.telegram.org.