Yaltopia-Tickets-App/DESIGN.md

---
name: Yaltopia Tickets App
description: Mobile invoice companion — Scan. Send. Reconcile.
colors:
  primary: "#E46212"
  orange-deep: "#CC580E"
  primary-foreground: "#FFF9F4"
  background: "#FFFFFF"
  foreground: "#251615"
  card: "#FFFFFF"
  card-foreground: "#251615"
  secondary: "#FFE2D8"
  secondary-foreground: "#422520"
  accent: "#FFDECF"
  accent-foreground: "#422520"
  muted: "#FFEAE3"
  muted-foreground: "#765D58"
  destructive: "#EF435E"
  destructive-foreground: "#FFF9F4"
  border: "#EDD5D1"
  input-border: "#F4CEC6"
  ring: "#E95752"
  popover: "#FFF9F4"
  popover-foreground: "#251615"
typography:
  display:
    fontFamily: "DMSans-ExtraBold, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif"
    fontSize: 36
    fontWeight: 800
    lineHeight: 1.125
    letterSpacing: -0.02
  headline:
    fontFamily: "DMSans-SemiBold, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif"
    fontSize: 30
    fontWeight: 600
    lineHeight: 1.2
    letterSpacing: -0.01
  title:
    fontFamily: "DMSans-SemiBold, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif"
    fontSize: 20
    fontWeight: 600
    lineHeight: 1.3
    letterSpacing: -0.01
  body:
    fontFamily: "DMSans-Regular, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif"
    fontSize: 16
    fontWeight: 400
    lineHeight: 1.5
  label:
    fontFamily: "DMSans-Medium, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif"
    fontSize: 14
    fontWeight: 500
    lineHeight: 1.25
rounded:
  sm: "6px"
  md: "8px"
  lg: "10px"
  xl: "12px"
  full: "9999px"
spacing:
  xs: "4px"
  sm: "8px"
  md: "16px"
  lg: "24px"
  xl: "32px"
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.primary-foreground}"
    rounded: "{rounded.md}"
    padding: "16px 16px"
    size: "40px"
  button-outline:
    backgroundColor: "transparent"
    textColor: "{colors.foreground}"
    rounded: "{rounded.md}"
    border: "1px solid {colors.border}"
    padding: "16px 16px"
    size: "40px"
  button-secondary:
    backgroundColor: "{colors.secondary}"
    textColor: "{colors.secondary-foreground}"
    rounded: "{rounded.md}"
    padding: "16px 16px"
    size: "40px"
  button-ghost:
    backgroundColor: "transparent"
    textColor: "{colors.foreground}"
    rounded: "{rounded.md}"
    padding: "16px 16px"
    size: "40px"
  card:
    backgroundColor: "{colors.card}"
    textColor: "{colors.card-foreground}"
    rounded: "{rounded.xl}"
    padding: "16px 16px"
    border: "1px solid {colors.border}"
  input:
    backgroundColor: "{colors.card}"
    textColor: "{colors.foreground}"
    rounded: "{rounded.md}"
    border: "1px solid {colors.input-border}"
    height: "40px"
    padding: "8px 12px"
---

# Design System: Yaltopia Tickets App

## 1. Overview

**Creative North Star: "The Mobile Desk"**

A warm, approachable, human workspace in your pocket. Yaltopia feels like a capable desk you carry with you — organized, reliable, and unpretentious. The orange primary (#E46212) anchors the system with warmth and confidence; it's present but not overwhelming, like a trusted tool within reach.

This system rejects corporate sterility (no navy-and-gray enterprise aesthetics) and consumer playfulness (no cartoonish illustrations or gamified elements). Every surface is flat with subtle borders — depth is communicated through clean edges and deliberate spacing, not shadows. The palette draws warmth from the Ethiopian context without resorting to default cream backgrounds or AI-generic warm tints: the background is true white, and warmth lives in the orange primary and the peach secondary/accent tones.

**Key Characteristics:**
- Flat surfaces, clean borders, no shadows at rest
- Warm orange confidence without aggression
- True white backgrounds, not tinted cream
- DM Sans across the board — one family, multiple weights
- Thumb-friendly mobile layout — primary actions in easy reach

## 2. Colors

A warm-neutral palette anchored by a confident orange. Light mode carries the full system; dark mode inverts to a near-black base while keeping the same orange primary and shifting accent from peach to purple for contrast.

### Primary
- **Burnt Orange** (#E46212): Primary actions, active tab indicators, key CTAs. The brand's confident voice. Use on ≤20% of any screen — its rarity is the point.
- **Orange Deep** (#CC580E): Pressed state for primary buttons and active interactive elements.

### Secondary
- **Blush Tint** (#FFE2D8): Subtle secondary surfaces, toggle backgrounds, secondary button fills. Warm without competing with primary.

### Accent
- **Soft Peach** (#FFDECF): Light accent surfaces, tag/chip backgrounds, ghost button hover states. Soft, supportive, never dominant.
- **Dark Accent — Lavender** (#E47DFB purple in dark mode): The accent shifts dramatically in dark mode to provide contrast against the dark backgrounds.

### Neutral
- **True White** (#FFFFFF): Body background, card surfaces. Clean, un-tinted.
- **Ink** (#251615): Body text, headings, icons. A warm near-black, not pure #000.
- **Warm Stone** (#765D58): Muted text, secondary labels, placeholder copy. Chosen to be readable (4.5:1 on white) without the washed-out gray of AI defaults.
- **Rose Mist** (#EDD5D1): Borders, dividers, card outlines. Visible but quiet.
- **Coral Haze** (#F4CEC6): Input borders, unfocused fields.

### Destructive
- **Crimson** (#EF435E): Destructive actions, error states, deletion.

### Named Rules

**The Flat Edge Rule.** Never use box-shadows on surfaces at rest. All depth is communicated through borders and spacing. The only shadows in the system are on the floating tab bar (ambient lift to distinguish the navigation layer from content).

**The One Orange Rule.** The primary orange appears on ≤20% of any screen. Buttons, active tabs, and no more. If it covers more surface than that, the interface is shouting.

## 3. Typography

**Display Font:** DM Sans ExtraBold (system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif)
**Body Font:** DM Sans Regular (same stack)
**Label Font:** DM Sans Medium (same stack)

One family, three weights. The palette of weight (400, 500, 600, 800) creates hierarchy without switching typefaces. Clean, contemporary, readable at small mobile sizes.

### Hierarchy
- **Display** (800, 36px, 1.125): Screen headings — h1 usage only. Reserved for hero numbers and page titles.
- **Headline** (600, 30px, 1.2): Section titles — h2. Has a bottom border to visually separate sections.
- **Title** (600, 20px, 1.3): Card titles, modal headers — h4.
- **Body** (400, 16px, 1.5): Primary reading text, list content, descriptions. Target 65–75ch line length on tablets.
- **Label** (500, 14px, 1.25): Button text, form labels, small print. Also used for small (14px font-medium) and muted (14px with muted-foreground color).

### Named Rules
**The Single Family Rule.** No second typeface. If the hierarchy needs more contrast, reach for weight (800 vs 400), not a new font. DM Sans's range from Regular to ExtraBold provides enough range.

## 4. Elevation

Flat by default. Surfaces are distinguished by borders (`rose-mist` #EDD5D1, 1px), not by shadows. The only exception is the floating tab bar, which uses a soft shadow (`shadow-slate-200/60`) to visually separate the navigation layer from scrollable content. On Android, minimal elevation (2-4) is applied to pressable surfaces for tactile feedback.

In dark mode, all shadows disappear entirely. Depth is conveyed through surface color contrast (card #1F1F1F on background #161616) and border visibility.

## 5. Components

### Buttons
- **Shape:** Gently rounded corners (8px, `rounded-md`).
- **Primary (Burnt Orange):** Background #E46212, white text (#FFF9F4). Active state darkens to #CC580E. Internal padding: 16px horizontal, 10px vertical (h-10).
- **Outline:** Transparent background, 1px border (#EDD5D1), ink text (#251615).
- **Secondary (Blush Tint):** Background #FFE2D8, dark text (#422520). For less prominent actions.
- **Ghost:** No background or border. Accent background on press.
- **Sizes:** Default (h-10 px-4), Small (h-9 px-3), Large (h-11 px-6), Icon (h-10 w-10).
- **Disabled:** 50% opacity, no pointer events.

### Cards
- **Corner Style:** Rounded corners (12px, `rounded-xl`).
- **Background:** Card white (#FFFFFF), border 1px solid rose-mist (#EDD5D1).
- **Shadow Strategy:** None (see Elevation — Flat Edge Rule).
- **Internal Padding:** 16px horizontal (CardContent uses px-4, CardHeader px-6).

### Inputs / Fields
- **Style:** 1px solid coral-haze (#F4CEC6), rounded 8px (`rounded-md`), white background.
- **Focus:** Ring treatment (3px ring at #E95752 with 50% opacity on web).
- **Error:** Red border + ring (destructive #EF435E).
- **Disabled:** Reduced opacity.

### Navigation (Tab Bar)
- **Style:** Floating pill, centered horizontally with 20px margins. Border-radius 32px. White background in light mode, card-dark (#1F1F1F) in dark.
- **Position:** Absolute, bottom 25px from screen edge.
- **Active tab:** Icon in burnt orange (#E46212), with a 10px semi-transparent orange background pill.
- **Inactive tab:** Icon in slate (#94a3b8).
- **Scan FAB:** Circular orange button (h-16 w-16), elevated -12px above the bar, white border separating it.

### Chips / Filter Pills
- **Style:** Sharp rectangular (4px radius), 16px horizontal padding, 6px vertical. Small uppercase label (9px, 700 weight, wide tracking).

## 6. Do's and Don'ts

### Do:
- **Do** use Burnt Orange (#E46212) sparingly — CTAs, active indicators, the scan FAB. Its rarity is the point.
- **Do** use True White (#FFFFFF) backgrounds. No cream, beige, sand, or warm-tinted neutrals.
- **Do** use DM Sans across the entire app — weight contrast creates hierarchy.
- **Do** use flat surfaces with borders for depth. No shadows on cards, buttons, or containers.
- **Do** use uppercase labels only for short badges and section labels (9px, 700 weight, wide tracking).
- **Do** follow the shadcn/ui convention: CSS custom properties as RGB comma-separated values, consumed by Tailwind via `rgba(var(--X), <alpha-value>)`.

### Don't:
- **Don't** use box-shadow and border together on the same element — pick one (border for cards, neither for buttons at rest).
- **Don't** use gradient text, glassmorphism, side-stripe borders, or hand-drawn SVG illustrations.
- **Don't** use generic AI-default palettes (cream backgrounds, warm-tinted neutrals, flat gray body text).
- **Don't** exceed 3 font families. One family (DM Sans) is the rule.
- **Don't** use all-caps for body copy or headings longer than 4 words.
- **Don't** make the interface look corporate (navy, heavy grays, enterprise sterility), cartoonish (playful mascots, gamification), or cluttered (information without hierarchy).