Give content room to grow
Begin at 375 px with at least 16 px side gutters, 16 px body text and 44 px touch targets. Stack content when space runs out. Long titles and Russian text need room to wrap.
Gem / Interface guide
Make your app feel like it belongs
People arrive from Telegram with habits: where to tap, how to go back, what a link looks like. Keep those habits working. Use these defaults for the frame, then design the content around what your app does.
Readable on a phone, usable by touch
Keep the frame predictable
The 48 px bar gives every app the same landmarks: Build, its name and Share. Respect the safe inset above it, and keep your content clear of the frame and keyboard.
Use the theme they chose
Read Telegram’s theme colors and respond when they change. In a browser, follow the operating system. Keep the same hierarchy and controls in both light and dark modes.
Start from the working defaults
Theme and safe-area integration
// Load gem-defaults.css after the existing injected defaults.
// Update these on theme and viewport changes.
const root = document.documentElement;
root.dataset.theme = gem.dark ? 'dark' : 'light';
root.style.setProperty('--gem-safe-top', gem.safe.top + 'px');
root.style.setProperty('--gem-safe-bottom', gem.safe.bottom + 'px');
// Existing hooks stay unchanged:
// #gem-bar · #gem-screen · .gem-btn · .gem-btn2
// Use the host’s existing share handler and keyboard shortcuts.The client library supplies Telegram’s --tg-theme-* variables. Keep its viewport and input handling intact. Use Noto Sans and the current style-guide tokens; update the safe insets whenever the host’s viewport changes.
One card, one result
A card should still make sense when someone finds it later. Lead with the question or app name, show the result, then offer an action. Telegram supplies the typography.
Weather in Dubai
32 °C · Clear
Cooling to 28 °C this evening.
Updated 5 min ago
32 °C · Clear
Cooling to 28 °C this evening.
Updated 5 min ago
Gem-Pong
Play someone new or take on the computer.
Play someone new or take on the computer.
Example card text
Weather in Dubai 32 °C · Clear Cooling to 28 °C this evening. Updated 5 min ago [ ↻ Update (2) ] [ Save ] [ Share ]
Keep the question, latest answer and update time together. Change the action’s label while it works: ◌ Updating… followed by ✓. A failed update must leave the previous answer visible. Use Open for an app card.
Separate using from managing
Someone returning to a saved app wants to use it. Keep Open and Share easy to find in Cards. Those actions should feel the same whether the person made the app or received it from a friend.
An owner also needs to edit, inspect activity and update source material. Those controls live under /myapps in the bot; the dashboard in Settings links to owned apps too. Keep management out of the experience you share with other people.