# Design System — Desi Clans

**Version:** 1.0  
**Last updated:** 2026-04-04

---

## 1. Brand intent

Desi Clans should read as **premium editorial culture**, not a discount ticket site.

- **Cinematic:** Full-bleed imagery, deliberate negative space, restrained color.
- **Warm, not loud:** Celebratory without carnival clutter.
- **Bengaluru-rooted:** Urban sophistication + festival energy.
- **Trust:** Clear dates, venues, and pricing; no dark patterns on checkout.

---

## 2. Design principles

1. **Content leads** — Photography and event title dominate; UI chrome stays quiet.
2. **Mobile first** — Design at 390px width; scale up with fluid typography.
3. **Motion with purpose** — GSAP for hero reveals and section entrances; never block interaction.
4. **Accessible by default** — Color is not the only signal; focus states are always visible.
5. **Performance is UX** — Prefer CSS transforms for animation; lazy-load below-fold media.

---

## 3. Color (Tailwind tokens)

Define in `tailwind.config.js` under `theme.extend.colors`:

| Token | Role | Suggested value | Usage |
|-------|------|-----------------|--------|
| `ink` | Primary text | `#0F0E0C` | Headlines, body |
| `ink-muted` | Secondary text | `#5C574F` | Meta, captions |
| `surface` | Page background | `#FAF8F5` | Default canvas |
| `surface-elevated` | Cards | `#FFFFFF` | Cards, modals |
| `accent` | Primary CTA | `#C45C26` | Buttons, links (terracotta) |
| `accent-hover` | CTA hover | `#A34A1E` | Hover states |
| `gold` | Highlight | `#C9A227` | Featured badges, dividers (sparingly) |
| `festival` | Seasonal accent | `#8B2E5A` | Holi/Garba campaign strips (optional per edition) |
| `border` | Dividers | `#E8E4DD` | Hairlines |
| `success` | Valid ticket | `#2D6A4F` | Check-in success |
| `danger` | Errors | `#B42318` | Form errors |

**Dark sections:** Hero and footer may use `ink` background with `surface` text for contrast blocks—use for one section per page max.

---

## 4. Typography

Use **two families** only (load via Google Fonts or self-host):

| Role | Family | Tailwind class | Notes |
|------|--------|----------------|-------|
| Display | *Fraunces* or *Playfair Display* | `font-display` | H1–H2, editorial pull quotes |
| UI / body | *DM Sans* or *Inter* | `font-sans` | Body, buttons, labels |

**Scale (mobile-first)**

| Element | Size | Weight | Tracking |
|---------|------|--------|----------|
| H1 | `text-4xl` → `md:text-6xl` | 600 | tight |
| H2 | `text-3xl` → `md:text-4xl` | 600 | tight |
| H3 | `text-xl` | 600 | normal |
| Body | `text-base` | 400 | normal |
| Small / meta | `text-sm` | 400 | `text-ink-muted` |
| Button | `text-sm` uppercase | 600 | `tracking-wide` |

**Line length:** Prose blocks `max-w-prose` (~65ch).

---

## 5. Spacing & layout

- **Grid:** 4px base; use Tailwind spacing scale consistently.
- **Page gutters:** `px-4` mobile, `px-6` tablet, `px-8` desktop; `max-w-7xl mx-auto` for content.
- **Section rhythm:** `py-16` md:`py-24` between major sections.
- **Cards:** `rounded-2xl`, subtle shadow `shadow-sm`, border `border-border`.

---

## 6. Components (catalog)

Build in `frontend/src/components/` with consistent naming:

| Component | Description |
|-----------|-------------|
| `Button` | Primary, secondary (outline), ghost; min height 44px touch target |
| `Badge` | Event type, featured, sold out |
| `EventCard` | Cover, title, date, venue, CTA |
| `EventHero` | Full-width cover + gradient scrim + title |
| `MediaGallery` | Grid + lightbox (keyboard trap, focus return) |
| `TicketCTA` | Sticky on mobile for detail page |
| `Navbar` | Logo, Events, Subscribe; drawer on mobile |
| `Footer` | Links, social, newsletter |
| `Input`, `Label`, `FormError` | Accessible form primitives |
| `Skeleton` | Loading placeholders matching card layout |
| `AdminShell` | Sidebar + content (separate visual tone: denser, neutral) |

**Icons:** Lucide React only; size `20` inline, `24` in buttons.

---

## 7. Motion (GSAP + ScrollTrigger)

**Setup**

- Register `ScrollTrigger` once in `animations/gsap.js`.
- Export `prefersReducedMotion()` helper; if true, skip timelines and set final state.

**Patterns**

| Pattern | Use | Duration |
|---------|-----|----------|
| Hero fade + y | Home hero | 0.8–1.2s |
| Stagger cards | Event grid on scroll | 0.4s stagger |
| Parallax (subtle) | Hero image only | scrub 0.5 |

**Rules**

- No infinite loops on main content.
- `will-change` only during active animation.
- Do not animate `width`/`height`; use `transform` and `opacity`.

---

## 8. Photography & imagery

- **Aspect ratios:** Hero 16:9 or 3:2; cards 4:5 or 3:2.
- **Treatment:** Slight gradient overlay (`from-ink/60`) for text on images.
- **Alt text:** Required; describe the scene, not "event image".
- **Placeholders:** Neutral `surface` with shimmer skeleton, not gray boxes.

---

## 9. Accessibility

- Minimum touch target **44×44px**.
- Focus ring: `ring-2 ring-accent ring-offset-2 ring-offset-surface`.
- Color contrast: body text ≥ 4.5:1; large text ≥ 3:1.
- `prefers-reduced-motion`: disable ScrollTrigger scrubbing.
- Forms: associate labels, `aria-invalid`, `aria-describedby` for errors.
- Skip link: "Skip to main content" as first focusable element.

---

## 10. Admin UI tone

Admin is **utilitarian**, not marketing:

- Neutral `surface` background, compact table density.
- Same `font-sans`; skip display font in admin except page titles.
- Primary actions still use `accent` for consistency.

---

## 11. Content voice

- **Headlines:** Specific ("Garba Under the Lights — KTPO Whitefield") not generic ("Amazing Night").
- **CTAs:** "Get tickets", "View edition", "Join the list" — avoid "Click here".
- **Venues:** Always city + venue name when known.

---

## 12. Tailwind configuration checklist

- `content: ['./index.html', './src/**/*.{js,jsx}']`
- Extend `colors`, `fontFamily`, `borderRadius` as above
- No `@apply` abuse; prefer utility classes in JSX for clarity
- `plugins`: only `@tailwindcss/forms` if needed for input resets

---

## 13. Do not use

- Neon gradients, glassmorphism stacks, or concert-poster clutter.
- More than two font families.
- Auto-playing video with sound.
- Icon-only buttons without `aria-label`.

---

## 14. References

- [PRD.md](./PRD.md) — product scope  
- [ARCHITECTURE.md](./ARCHITECTURE.md) — frontend structure