Desi-Clans/docs/DESIGN_SYSTEM.md

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 — product scope
• ARCHITECTURE.md — frontend structure