Javed Nihari Design System

Overview

Javed Nihari's digital presence embodies the warmth and authenticity of Karachi's most storied Nihari house, translated into a contemporary food-ordering interface that feels both trustworthy and inviting. The design rests on a near-white canvas layered with translucent glass surfaces—creating a sense of depth without visual noise—that allows photography and menu content to command full attention. The color philosophy is restrained almost to minimalism: near-black ink ({colors.ink}) handles all textual communication, while the brand's primary voltage ({colors.primary}) is deployed sparingly on high-affordance CTAs where conversion intent is explicit.

The typographic voice is carried entirely by Poppins, a geometric humanist sans-serif whose circular counters and open apertures read as friendly and accessible—ideal for a culinary brand seeking to feel both established and approachable. Hierarchy is achieved through a disciplined weight progression (400 → 500 → 600 → 700) rather than aggressive size jumps, giving body copy a comfortable reading rhythm while allowing display text to assert itself through bolder presence. The shape language is distinctly app-native: {rounded.pill} buttons, {rounded.full} icon containers, and {rounded.lg} content cards signal touch-first interaction patterns that translate seamlessly between desktop ordering flows and mobile tap interfaces.

Two sub-systems are evident in the architecture. The carousel dialect dominates the above-fold experience—a signature horizontal showcase with floating navigation pills, dot indicators, and generous internal padding that treats each slide as a mini-landing-zone. The skeleton/loading dialect supports perceived performance through shimmer-animated placeholder shapes that mirror the final card geometry, maintaining layout stability during content fetches. A third, emerging menu-grid dialect appears below the fold, organizing dish cards into responsive columns with consistent gutters and elevation treatment.

Key Characteristics:

• Canvas is {colors.surface-soft} (near-white) with {colors.surface-glass} translucent overlays creating layered depth
• All body text renders in {typography.body-md} (Poppins 16px/400) for optimal recipe readability
• Primary CTAs use {component.button-primary} with {colors.primary} background and {rounded.pill} geometry
• Content cards employ {component.card} with {rounded.lg} corners and {extensions.shadows.sm} elevation
• Carousel navigation relies on {component.carousel-nav-button} (40px circular {component.button-icon} variants)
• Skeleton states use {component.skeleton-line}, {component.skeleton-circle}, and {component.skeleton-title} with shimmer animation
• Section vertical rhythm is set by {spacing.section} (80px) with hero areas receiving {spacing.hero} (157px)
• Hairline borders ({colors.hairline-soft}) separate navigational zones without harsh visual division

Colors

Brand & Accent

• Primary ({colors.primary} — #030000): Near-black brand color used exclusively on primary action buttons ({component.button-primary}), active category chips ({component.category-chip-active}), and active carousel dots ({component.carousel-dot-active}). Carries the full weight of brand conversion intent.
• Primary Active ({colors.primary-active} — #050000): Slightly lightened press state for primary buttons, providing tactile feedback on interaction.
• Primary Hover ({colors.primary-hover} — #040000): Intermediate hover state bridging default and active; implement per stack conventions.
• Accent ({colors.accent} — #1a1a1a): Dark charcoal reserved for secondary emphasis marks, price typography, and decorative elements requiring less dominance than primary.

Surface

• Canvas ({colors.canvas} — #010000): The theoretical document root; actual visible background is {colors.surface-soft}.
• Surface ({colors.surface} — #f5f5f5): Neutral gray used as the carousel container background ({component.carousel-container}) and page-level section alternation.
• Surface Soft ({colors.surface-soft} — #fafafa): The dominant visible background—hero bands, page body, and card parent containers rest on this near-white.
• Surface Strong ({colors.surface-strong} — #e5e5e5): Medium gray for badges ({component.badge}), disabled surfaces, and divider-like backgrounds.
• Surface Elevated ({colors.surface-elevated} — #ffffff): Pure white for raised elements—cards ({component.card}), buttons ({component.button-secondary}), inputs ({component.text-input}), and modals ({component.modal-sheet}).
• Surface Glass ({colors.surface-glass} — rgba(255, 255, 255, 0.80)): Translucent white with backdrop-blur for the top navigation bar ({component.top-nav}), creating frosted-glass separation from scrolling content.
• Surface Glass Strong ({colors.surface-glass-strong} — rgba(255, 255, 255, 0.95)): Higher-opacity glass variant for the scrolled nav state ({component.top-nav-scrolled}), increasing legibility as user scrolls.

Text

• Ink ({colors.ink} — #030000): Darkest text color for headings, primary body copy, and high-emphasis UI labels.
• Body ({colors.body} — #1a1a1a): Slightly softer black for extended reading passages, descriptions, and secondary headings.
• Muted ({colors.muted} — #6b7280): Medium gray for supporting text—captions, metadata timestamps, placeholder hints.
• Muted Soft ({colors.muted-soft} — #9ca3af): Light gray for truly secondary information—disabled labels, inactive dot indicators ({component.carousel-dot-inactive}).
• On Primary ({colors.on-primary} — #ffffff): White text guaranteed AA contrast against {colors.primary}; used on all primary buttons and active states.
• On Dark ({colors.on-dark} — #ffffff): Reserved for any future dark-mode surfaces or overlay text.
• On Surface ({colors.on-surface} — #030000): Alias for ink when referencing text-on-surface semantics explicitly.

Hairlines & Borders

• Hairline ({colors.hairline} — #e5e7eb): Light gray border for card outlines, input fields, and structural dividers.
• Hairline Soft ({colors.hairline-soft} — rgba(229, 231, 235, 0.50)): Semi-transparent variant for nav bottom borders ({component.top-nav}) that softens the visual break.
• Border Strong ({colors.border-strong} — #d1d5db): Visible gray for focus rings, error states, and emphasized container edges.

Semantic

• Error ({colors.error} — #dc2626): Red for form validation failures, out-of-stock indicators, and destructive actions.
• Success ({colors.success} — #16a34a): Green for order confirmations, availability status, and positive feedback.
• Warning ({colors.warning} — #ca8a04): Amber for low-stock alerts, delivery delays, and cautionary notices.
• Info ({colors.info} — #2563eb): Blue for informational toasts, help links, and external references.
• Link ({colors.link} — #2563eb): Standard blue hyperlink color for embedded navigation within text blocks.
• Link Active ({colors.link-active} — #1d4ed8): Darker blue for visited or pressed link states.

Skeleton / Loading

• Skeleton Base ({colors.skeleton-base} — #e5e7eb): Light gray fill for all loading placeholder shapes before shimmer animation applies.
• Skeleton Highlight ({colors.skeleton-highlight} — #f3f4f6): Lighter gray that sweeps across skeleton shapes during the shimmer keyframe animation.

Typography

Font Family

The entire type system runs on Poppins, a Google Fonts-available geometric sans-serif designed by Indian Type Foundry. Poppins is loaded via self-hosted WOFF2 files with unicode-range splitting for Latin, Latin Extended, and Devanagari scripts—ensuring optimal payload delivery for the restaurant's bilingual audience (English menu + potential Urdu support). Fallback is declared as "Poppins Fallback", sans-serif for graceful degradation. Four weights are available in the loaded font-face declarations: 400 (Regular), 500 (Medium), 600 (SemiBold), and 700 (Bold). Poppins' circular letterforms and uniform stroke width give the brand a modern, clean persona that complements the food photography without competing for attention.

Hierarchy

| Token | Size | Weight | Line Height | Letter Spacing | Use | |---|---|---|---|---|---| | {typography.display-xl} | 48px | 700 | 1.15 | -0.02em | Hero headlines, campaign titles | | {typography.display-lg} | 32px | 600 | 1.2 | -0.01em | Section headings, feature titles | | {typography.title-md} | 20px | 600 | 1.4 | 0 | Card titles, sub-section heads | | {typography.title-sm} | 18px | 600 | 1.35 | 0 | Menu item names, pricing labels | | {typography.body-md} | 16px | 400 | 1.5 | 0 | Paragraph text, descriptions | | {typography.body-sm} | 14px | 400 | 1.43 | 0 | Secondary descriptions, metadata | | {typography.caption} | 13px | 400 | 1.38 | 0 | Timestamps, fine print | | {typography.label-md} | 14px | 500 | 1.4 | 0.01em | Buttons, chips, tags | | {typography.button} | 14px | 500 | 1.25 | 0 | Standard button text | | {typography.button-lg} | 16px | 600 | 1.25 | 0 | Large/primary button text |

Principles

The typography system trusts weight progression over dramatic size jumps to establish hierarchy. Body copy sits comfortably at 16px/400—a size optimized for recipe descriptions and menu item details that users may read at length while deciding orders. Headings gain authority through 600–700 weights rather than pushing beyond 48px, keeping the vertical rhythm compact and scroll-efficient for mobile users. Display text employs modest negative letter-spacing (-0.01em to -0.02em) at larger sizes to optically tighten word shapes without affecting readability at body scales.

Button and label text breaks from body conventions by using medium (500) or semibold (600) weights at smaller sizes (14–16px)—this ensures CTAs remain scannable even when surrounded by dense menu information. The system avoids italic or uppercase transformations entirely; emphasis is conveyed through weight and color contrast alone, maintaining the brand's calm, straightforward voice. Price typography specifically uses {typography.title-sm} (18px/600) to make costs instantly locatable without resorting to aggressive coloring or sizing.

Note on Font Substitutes

Poppins is freely available on Google Fonts and requires no proprietary substitution. For offline or restricted-network environments, Nunito serves as the closest open-source equivalent—sharing similar geometric proportions, circular counters, and a matching weight range (400–700). Define CSS variables as follows if substitution is necessary:

:root {
  --font-poppins: "Poppins", "Nunito", -apple-system, BlinkMacSystemFont, sans-serif;
}

Layout

Spacing System

• Base unit: 4px (half the smallest defined token {spacing.xs}).
• Tokens: {spacing.xxs} (2px — micro-adjustments, focus ring offsets), {spacing.xs} (4px — icon padding internals, tight gaps), {spacing.sm} (8px — inline element gaps, compact padding), {spacing.md} (16px — standard card padding, grid gaps, container margins), {spacing.lg} (24px — spacious card interiors, section-internal spacing), {spacing.xl} (32px — major component separation, modal padding), {spacing.section} (80px — vertical section breaks, footer padding), {spacing.hero} (157px — hero band vertical padding, signature tall spacing for above-fold impact).
• Section padding (vertical): {spacing.section} — applied to hero band ({component.hero-band}) and footer ({component.footer}) zones.
• Card internal padding: {spacing.lg} (24px) on {component.card} and {component.card-elevated}; {spacing.xl} (32px) on {component.carousel-container}.
• Gutters: Grid gap of 20px–24px ({spacing.md} to {spacing.lg}) between menu cards in the responsive grid; 16px ({spacing.md}) horizontal page margin on mobile, scaling to 24px+ on desktop via max-w-7xl mx-auto px-3/sm:px-4.

Grid & Container

• Max content width: 1280px (max-w-7xl in Tailwind, approximately 80rem), centered with auto margins.
• Editorial density: medium-low — generous whitespace between menu categories and carousel slides prioritizes visual breathing room over information density, appropriate for a discovery-oriented food ordering experience.
• Desktop grid behavior: 3-column layout for menu item cards (grid-cols-1 sm:grid-cols-2 md:grid-cols-3), collapsing responsively. Carousel content occupies full container width with internal padding handling alignment.
• Hero column split: Single-centered column for headline/CTA content within the hero band; carousel operates as a full-width horizontal showcase below.

Whitespace Philosophy

The system embraces editorial-airy whitespace as a deliberate brand signal—each menu category gets its own breathing room, carousel slides are framed with 32px+ internal padding, and the hero area commands 157px of vertical presence. This openness counterbalances the potentially dense information load of a full menu, making individual dishes feel curated rather than cataloged. Whitespace is never empty; it's structural, guiding the eye from category chip to featured item to grid card in a deliberate scanning path.

Header Architecture

┌──────────────────────────────────────────────────────────────┐
│ [Logo]          Navigation Links             [Cart] [Menu]  │ ← top-nav (48px, glass bg)
├──────────────────────────────────────────────────────────────┤
│                                                              │
│                    [Hero Content Area]                       │ ← hero-band (157px v-padding)
│                                                              │
├──────────────────────────────────────────────────────────────┤
│ [←]                                                    [→]   │ ← carousel-nav-buttons (40px circles)
│                                                              │
│     ┌─────────────────────────────────────────┐             │
│     │                                           │             │
│     │         Carousel Slide Content            │             │ ← carousel-container (xl radius)
│     │         (skeleton / image / text)         │             │
│     │                                           │             │
│     └─────────────────────────────────────────┘             │
│                                                              │
│                  [●] [○] [○] [○]                   [☐][☐]   │ ← dots + view toggle
│                                                              │
├──────────────────────────────────────────────────────────────┤
│  [Category Chips Row: All | Nihari | Biryani | ... ]        │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                    │
│  │  Card 1  │  │  Card 2  │  │  Card 3  │                    │ ← 3-col grid
│  │          │  │          │  │          │                    │
│  └──────────┘  └──────────┘  └──────────┘                    │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Hero Section

The hero area combines a gradient background band (bg-gradient-to-b from-gray-50 to-white) transitioning from {colors.surface} to {colors.surface-soft}, creating a subtle wash that separates the above-fold promotional zone from the content grid below. Within this band, the carousel container ({component.carousel-container}) acts as the primary focal point—its {rounded.xl} (20px) corners and {extensions.shadows.md} elevation lift it from the background, while the skeleton state (visible in the reference screenshot) shows the loading anatomy: a title bar ({component.skeleton-title}), a central circle placeholder ({component.skeleton-circle}) likely for dish imagery, supporting lines ({component.skeleton-line}), and a caption row ({component.skeleton-caption}).

Navigation is handled by two {component.carousel-nav-button} instances positioned absolutely left and right of the container—40px circular buttons with {colors.surface-elevated} backgrounds and {extensions.shadows.sm} depth. Below the slide content, a centered {component.carousel-dots-container} holds pill-shaped dot indicators: the active dot ({component.carousel-dot-active}) fills with {colors.ink}, while inactive dots ({component.carousel-dot-inactive}) remain transparent with {colors.muted-soft} borders. A view-toggle control (grid/list icons) sits flush-right in this control bar.

Category Chip Bar

Below the carousel, a horizontal scrollable row of {component.category-chip} elements allows menu filtering. Active chips ({component.category-chip-active}) invert to {colors.primary} background with {colors.on-primary} text; inactive chips show {colors.surface-elevated} with {colors.ink} text. Each chip uses {rounded.pill} geometry and {typography.label-md} for scannability.

Menu Grid

The responsive grid (grid-cols-1 sm:grid-cols-2 md:grid-cols-3) lays out {component.card} instances with gap-5/sm:gap-6 (20px/24px) gutters. Each card represents a menu item with image, title ({typography.title-sm}), description ({typography.body-sm}), price ({typography.price-tag}), and add-to-cart action.

Elevation & Depth

| Level | Treatment | Use | |---|---|---| | 0 (Flat) | No shadow, {colors.surface-soft} or {colors.surface} background | Page body, hero band background, footer | | 1 (Hairline) | {extensions.shadows.sm} (0 1px 3px rgba(0,0,0,0.10)) | Top nav bar, icon buttons, badge containers | | 2 (Raised) | {extensions.shadows.md} (0 4px 6px rgba(0,0,0,0.10)) | Carousel container, elevated cards, dropdown menus | | 3 (Floating) | {extensions.shadows.lg} (0 10px 15px rgba(0,0,0,0.10)) | Modals, toasts, persistent action bars | | Focus | 2px solid {colors.border-strong} outline, optional offset | Text inputs on focus, keyboard-navigated buttons |

The elevation philosophy is layered-light: shadows never exceed 10% opacity black, and the deepest level ({extensions.shadows.lg}) is reserved for truly disruptive surfaces like modals that must break out of the document flow. Color plays a supporting role in depth perception—the glass nav backgrounds use translucency rather than shadow to separate from content, while the hero gradient provides atmospheric depth without any drop shadow at all. All shadows are neutral-toned (no cool/warm tint), keeping the visual temperature consistent with the brand's neutral palette.

Decorative Depth

The hero band employs a vertical gradient wash (from-gray-50 to-white) that creates a subtle luminance transition—darker at the top fading to pure white below. This is the only gradient in the system; it serves to anchor the carousel zone visually without introducing color that would compete with food photography. Skeleton placeholders use the shimmer animation—a sweeping highlight that moves left-to-right across {colors.skeleton-base} shapes—to indicate loading progress and maintain perceived responsiveness.

Shapes

Border Radius Scale

| Token | Value | Use | |---|---|---| | {rounded.sm} | 4px | Input focus highlights, micro-elements | | {rounded.DEFAULT} | 10px | Default card radius (overridden by specific components), skeleton lines, text inputs | | {rounded.md} | 14px | Secondary cards, panel interiors | | {rounded.lg} | 16px | Primary content cards ({component.card}), modal sheets | | {rounded.xl} | 20px | Carousel container ({component.carousel-container}), featured banners | | {rounded.pill} | 9999px | Buttons, chips, dots, badges — all interactive pill-shaped elements | | {rounded.full} | 9999px | Icon buttons, avatars, perfectly circular elements |

Photography Geometry

While the reference screenshot shows a skeleton state (no actual imagery loaded), the carousel's central {component.skeleton-circle} (120px diameter, fully rounded) indicates that circular crop is the intended treatment for hero/dish spotlight images. Menu grid cards likely use 4:3 or 16:9 aspect ratio images with {rounded.lg} (16px) corner clipping, contained within the card's top portion. Full-bleed treatments are not observed—all imagery appears containerized within rounded-corner cards or circular frames, maintaining the soft, app-like aesthetic throughout.

Components

No hover states documented. Hover behavior is unreliable to extract from a single screenshot. State variants live as separate entries in the components: frontmatter (e.g. {component.button-primary-active}, {component.text-input-focus}); add hover styling at implementation time per your stack's conventions.

Buttons

{component.button-primary} — The principal call-to-action button used for "Order Now," "Add to Cart," and conversion-critical actions. Background {colors.primary}, text {colors.on-primary} in {typography.button} (14px/500), fully rounded with {rounded.pill}, padded 10px 24px. State variant {component.button-primary-active} shifts to {colors.primary-active} on press. These buttons appear in the hero CTA zone, card footers, and sticky cart bars.

{component.button-secondary} — Tertiary action button for "View Menu," "Learn More," and non-destructive secondary paths. White ({colors.surface-elevated}) background with {colors.ink} text, same geometry and type as primary. Used alongside primary buttons to create visual hierarchy without color competition.

{component.button-outline} — Ghost/borderless variant for contextual actions like "Dismiss," "Cancel," or tertiary links within modals. Transparent background with {colors.ink} text, pill-rounded. Relies on proximity and position rather than fill to signal clickability.

{component.button-icon} — 40px square circular button ({rounded.full}) for standalone icon actions—carousel navigation arrows, close buttons, settings triggers. White background with {colors.ink} icon, {extensions.shadows.sm} elevation. The carousel's left/right navigation uses this component exclusively ({component.carousel-nav-button} references this same spec).

{component.button-icon-small} — Compact 32px version for density-constrained toolbars—inline actions within cards, minimized chrome. Same styling scaled down.

Cards & Containers

{component.card} — The foundational content container for menu items, features, and informational blocks. Pure white ({colors.surface-elevated}) background, {colors.ink} text in {typography.body-md}, {rounded.lg} (16px) corners, {spacing.lg} (24px) internal padding, {extensions.shadows.sm} elevation. Houses image, title, description, price, and action within a single cohesive rectangle.

{component.card-elevated} — Elevated card variant with {extensions.shadows.md} shadow for featured items, promotions, or "chef's choice" highlights that need to pop slightly from the grid. Identical dimensions and padding to standard card.

{component.carousel-container} — The signature horizontal showcase wrapping each promotional slide. {colors.surface} background, {rounded.xl} (20px) corners for maximum softness, {spacing.xl} (32px) padding creating generous internal margins, {extensions.shadows.md} elevation lifting it from the hero gradient. Contains the skeleton/image + text composite or loaded promotional content. Flanked by {component.carousel-nav-button} instances positioned absolutely.

{component.carousel-dots-container} — Horizontal pill-shaped container holding pagination dots. Transparent background, {colors.muted} text context, {rounded.pill} geometry, 8px 16px padding. Centers the dot group below the carousel slide area.

{component.carousel-dot-active} — Filled indicator for the current slide. {colors.ink} background (appearing as a filled pill), 24px × computed-height, {rounded.pill}. The active state is visually heavy to communicate current position unambiguously.

{component.carousel-dot-inactive} — Outline-only indicator for non-current slides. Transparent background with {colors.muted-soft} border (or text-color circle), same dimensions as active dot. The contrast between filled active and ghost inactive creates clear pagination semantics.

Inputs & Forms

{component.text-input} — Standard text entry field for search, quantity, and form inputs. White ({colors.surface-elevated}) background, {colors.ink} text in {typography.body-md}, {rounded.DEFAULT} (10px) corners, 10px 14px padding, 44px fixed height, {colors.hairline} border. State variant {component.text-input-focus} maintains same properties with border transition to {colors.border-strong} or focus-ring application per implementation.

Navigation

{component.top-nav} — The persistent header bar in default (scrolled-near-top) state. {colors.surface-glass} (80% white) background with backdrop-blur-sm, {colors.ink} text in {typography.body-sm}, 48px height, {colors.hairline-soft} bottom border, {extensions.shadows.sm} elevation. Contains logo (left), navigation links (center), and utility icons/cart (right). Max-width constrained to max-w-7xl centered.

{component.top-nav-scrolled} — Enhanced nav state after user scrolls past threshold. {colors.surface-glass-strong} (95% white) with backdrop-blur-md for increased frosted effect, 56px height (slightly taller), {extensions.shadows.md} deeper shadow, {colors.hairline} (full opacity) bottom border. The increased opacity ensures legibility of nav content over varying scroll positions.

{component.category-chip} — Filter chip for menu categorization. White background, {colors.ink} text in {typography.label-md} (14px/500), {rounded.pill}, 8px 20px padding. Appears in horizontal scrollable row below carousel. State variant {component.category-chip-active} inverts to {colors.primary} background with {colors.on-primary} text for the selected category.

Sub-Systems: Skeleton / Loading

{component.skeleton-line} — Rectangular placeholder simulating a line of text or content block. {colors.skeleton-base} background, {rounded.DEFAULT} (10px), 20px height, width varies by context (title vs. body line). Animated with shimmer keyframe that sweeps {colors.skeleton-highlight} across the shape.

{component.skeleton-circle} — Circular placeholder for avatar or featured image. {colors.skeleton-base}, {rounded.full}, 120px diameter (as observed in carousel center). The circle signals imagery will occupy this space.

{component.skeleton-title} — Wider line placeholder for heading text. {colors.skeleton-base}, {rounded.DEFAULT}, 28px height, ~60% width of container. Positioned at top of skeleton card structure.

{component.skeleton-caption} — Small pill placeholder for metadata or tag lines. {colors.skeleton-base}, {rounded.pill}, 12px height, narrow width. Positioned at bottom of skeleton structure.

Signature Components

{component.badge} — Small status indicator or tag. {colors.surface-strong} background, {colors.ink} text in {typography.caption} (13px/400), {rounded.pill}, 4px 12px padding. Used for "New," "Popular," "Spicy" labels on menu items.

{component.price-tag} — Dedicated typographic treatment for currency display. Transparent background (inherits card), {colors.ink} text in {typography.title-sm} (18px/600) for visual weight, no rounding. Placed prominently on each menu card.

{component.modal-overlay} — Full-viewport scrim behind modal sheets. rgba(0, 0, 0, 0.50) background, no rounding, covers entire screen to dismiss on click/tap-outside.

{component.modal-sheet} — Bottom-sheet or centered modal panel. {colors.surface-elevated} background, {colors.ink} text, {rounded.xl} top corners only (bottom corners 0px for sheet style), {spacing.lg} padding. Slides up via modalSlideUp animation.

{component.toast} — Temporary notification snackbar. White background, {colors.ink} text in {typography.body-sm}, {rounded DEFAULT}, 12px 20px padding, {extensions.shadows.md} elevation. Appears at viewport edge, auto-dismisses.

{component.footer} — Page footer container. {colors.canvas} (theoretical) / {colors.surface-soft} (actual) background, {colors.muted} text in {typography.body-sm}, {spacing.section} vertical padding, {spacing.md} horizontal padding. Contains links, legal, and branding.

Do's and Don'ts

Do

• Do use {typography.body-md} (16px/400) for all readable menu descriptions—this size optimizes for the average ordering decision read-time.
• Do apply {rounded.pill} to every clickable button, chip, and dot indicator—the consistently rounded interactive language is a core brand signature.
• Do reserve {colors.primary} exclusively for conversion actions (Add to Cart, Order Now, active states); never use it for decorative backgrounds or non-interactive text.
• Do wrap carousel slides in {component.carousel-container} with {rounded.xl} corners and {extensions.shadows.md} elevation to create the signature showcase depth.
• Do use {component.skeleton-line}, {component.skeleton-circle}, and {component.skeleton-title} with the shimmer animation during content loads—this maintains layout stability and perceived performance.
• Do constrain page content to max-w-7xl (1280px) centered with mx-auto—the design intentionally breathes with side margins on wide screens.
• Do apply backdrop-blur to nav backgrounds ({component.top-nav}, {component.top-nav-scrolled}) rather than solid opaque fills—the glass effect is a key depth cue.
• Do use {spacing.section} (80px) as the minimum vertical rhythm between major sections—compressing this breaks the editorial openness.
• Do keep button text in {typography.button} (14px/500) or {typography.button-lg} (16px/600)—never promote body text weight to buttons or demote button text to body weight.
• Do use {colors.hairline-soft} (50% opacity) for nav dividers and {colors.hairline} (100%) for content borders—the opacity difference signals structural vs. content boundaries.

Don't

• Don't substitute {colors.link} (blue) for {colors.primary} (near-black) on CTAs—link blue is for inline navigation only, not conversion actions.
• Don't use sharp corners (0px or {rounded.sm}) on content cards—{rounded.lg} (16px) minimum is required for the brand's soft aesthetic.
• Don't add gradient backdrops to the hero beyond the documented from-gray-50 to-white wash—any additional color competes with food imagery.
• Don't let carousel dots exceed 24px height or deviate from {rounded.pill} geometry—the pagination system is deliberately minimal and consistent.
• Don't apply {extensions.shadows.lg} to anything other than modals and toasts—level 3 elevation is reserved for flow-breaking surfaces.
• Don't mix font families within the interface—Poppins carries every role from display to caption; introducing a second face fragments the brand voice.
• Don't reduce {spacing.hero} (157px) below 100px for mobile—the tall hero is intentional vertical branding space, not wasted whitespace.
• Don't use {colors.ink} on {colors.ink} backgrounds—always ensure text contrasts against its immediate surface token ({colors.on-surface}, {colors.on-primary}, etc.).
• Don't create new radius values outside the defined scale ({rounded.sm} through {rounded.full})—the 8-step scale covers every observed geometry.
• Don't omit skeleton states for dynamically loaded content—the shimmer animation is an expected part of the loading UX, not an optional enhancement.

Motion & Animation

Transition Tokens

--transition-all: all 300ms ease;
--transition-color: color 300ms ease, background-color 300ms ease, border-color 300ms ease;
--transform-standard: transform 300ms ease;
--opacity-fade: opacity 300ms ease;

The extracted CSS declares a single blanket transition (all) with 300ms ease timing. For production implementation, this should be scoped to specific properties (color, transform, opacity) to avoid unintended layout thrashing. The recommended duration of 300ms aligns with the "moderate" motion level—noticeable but unhurried, appropriate for a dining/leisure context where rushed animations would feel incongruous.

Keyframe Animations

• shimmer — Sweeps a diagonal highlight ({colors.skeleton-highlight}) across skeleton placeholder shapes from left-to-right, creating the illusion of content loading in. Applied to {component.skeleton-line}, {component.skeleton-circle}, and {component.skeleton-title}.
• fadeInUp — Translates elements from 20px below final position while fading opacity 0→1. Used for scroll-triggered content reveals in the menu grid.
• slideInFromRight / slideInFromLeft — Horizontal entrance for modal sheets, side panels, or notification toasts sliding in from viewport edges.
• slideInFromBottom — Upward vertical slide for bottom-sheets and mobile keyboards.
• scaleIn — Scale transform from 0.95→1.0 with fade, giving modal/card appearances a subtle "pop" energy.
• modalOverlayIn — Fade-in for the {component.modal-overlay} backdrop (opacity 0→0.5).
• modalSlideUp — Paired with overlay: the {component.modal-sheet} translates from 100% below viewport to 0.
• categorySlideIn / categoryBounceSlide — Staggered horizontal entrance for the category chip row, with slight overshoot (bounce) on settle.
• addonFadeIn / itemModalAtcShine / itemModalAtcArrowNudge — Micro-animations for add-to-cart confirmation: fade-in quantity badge, shine sweep across the ATC button, nudge arrow icon.
• pulse — Subtle scale oscillation (1.0→1.05→1.0) for attention-drawing elements like live-order indicators.
• gradientShift / shimmerSlide — Background-position animations for gradient or shimmer effects on decorative surfaces.
• bounceIn — Elastic overshoot entrance for celebratory moments (order confirmed, achievement unlocked).
• fadeIn — Simple opacity 0→1 for straightforward appearances.

Interaction Patterns

• Carousel slide transitions: Horizontal translate with ease timing, ~300ms duration, no bounce. Dots update synchronously.
• Button press: Background color shift to {colors.primary-active} with 150ms transition (faster than standard for tactile response).
• Category chip selection: Background/color transition 200ms with slight scale (1.0→1.02→1.0) on the active chip.
• Scroll-triggered reveals: Menu grid cards fade-up sequentially with 80ms stagger between adjacent cards, triggered at 20% viewport intersection.
• Input focus: Border color transition to {colors.border-strong} over 150ms with optional 2px ring expansion.
• Modal open/close: Overlay fades 200ms; sheet slides up 300ms with slight deceleration (ease-out). Close reverses the sequence.
• Toast notifications: Slide in from right (desktop) or bottom (mobile), auto-dismiss after 3s with fade+slide-out.
• Skeleton shimmer: Continuous 1.5s loop (or single-play on mount) with linear timing for the highlight sweep.

Imagery Style

• Photography style: Food photography is expected to be warm, appetizing, and professionally shot—likely overhead or 45° angles emphasizing texture (nihari broth sheen, naan char, garnish detail). The circular carousel placeholder suggests hero shots may be cropped to circle or placed within circular frames.
• Color treatment: Images should feel naturally lit with warm color temperature (golden hour or soft studio lighting) to complement the neutral UI palette. Heavy filters or monochrome treatments would conflict with the clean, authentic brand voice.
• Role in hierarchy: Imagery is supporting-primary in the carousel (text + CTA lead, image reinforces) and primary-supporting in menu cards (image leads, text describes). Neither dominates exclusively; balance is key.
• Background integration: Images sit on {colors.surface-elevated} (white) card backgrounds—photography with natural white/negative space blends seamlessly; busy photos that clash with white cards should have subtle inner shadows or padding.
• Placeholder strategy: The comprehensive skeleton system ({component.skeleton-circle} for hero, rectangles for cards) indicates imagery is lazy-loaded or fetched asynchronously. Real images should fade in (fadeIn) replacing skeletons to avoid layout shift.
• No illustration or 3D detected: The design language is photographic-realistic; there is no evidence of flat illustration, isometric 3D, or abstract graphic elements in the current composition.
• Aspect ratios inferred: Hero/carousel image ~1:1 (square-ish, fitting the 120px circle placeholder); menu card images likely 4:3 or 16:9 landscape within the {rounded.lg} card frame.
• Icon imagery absent: No product icons, emoji decorations, or graphical embellishments observed—the UI relies on typography, color, and shape rather than illustrative ornamentation.

Icon System

• Library: Custom SVG (no detected third-party icon library such as Lucide, Heroicons, or Material Icons in the extracted CSS/font data). Icons appear to be inline SVGs or custom-designed vector assets.
• Specific icons observed: Left chevron/arrow-left (carousel previous), Right chevron/arrow-right (carousel next), Grid-view toggle, List-view toggle, Shopping cart (nav utility), Menu/hamburger (nav utility), Search magnifying glass (inferred for search input), Close/X (modal dismiss), Plus/minus (quantity controls—inferred).
• Treatment: Stroke-based icons (not filled), rendered in currentColor inheriting from parent {colors.ink} or {colors.on-primary} depending on context. Consistent 1.5–2px stroke width estimated.
• Size alignment: Nav and carousel icons are 20×20px (within 40px {component.button-icon} containers, yielding 10px padding); utility icons in the top nav are 18–20px; inline/action icons within cards are 16px.
• Accessibility: Icons appearing without text labels (carousel nav arrows) rely on aria-label attributes; icon-only buttons must include screen-reader-only text.

Recommended Frontend Stack

- Framework:      Next.js (App Router) — detected via __next_s script injection and React-style class composition
- Styling:        Tailwind CSS v3+ — utility classes (max-w-7xl, backdrop-blur-sm, grid-cols-3, rounded-[value]) pervasive in extracted DOM
- Fonts:          Self-hosted Poppins WOFF2 (current setup) OR Google Fonts CDN fallback; CSS variable --font-poppins for theming
- Animation:      Tailwind animate utilities + custom @keyframes (shimmer, fadeInUp, slideInFromRight, etc.) already defined in <style> blocks
- Icons:          Custom SVG components (inline React components or sprite sheet); consider Lucide for consistency if expanding icon set
- Component lib:  Custom components (no shadcn/radix detected); recommend building on raw Tailwind + Radix primitives for accessibility if needed

Responsive Behavior

Breakpoints

| Name | Width | Key Changes | |---|---|---| | Mobile | < 640px | Single-column grid, collapsed nav (hamburger), full-width carousel, 12px horizontal padding (px-3), stacked CTA | | Tablet | 640px – 1023px | Two-column grid (sm:grid-cols-2), expanded nav links visible, 16px padding (sm:px-4), side-by-side CTAs | | Desktop | 1024px – 1279px | Three-column grid (md:grid-cols-3), full horizontal nav, 20px+ padding, hover states enabled | | Wide | ≥ 1280px | Max-width container (1280px) centered with auto margins, comfortable gutters, enhanced spacing |

Touch Targets

• {component.button-primary} / {component.button-secondary}: ~44px height (10px padding × 2 + 24px text ≈ 44px), exceeds WCAG AAA 44×44 minimum ✓
• {component.button-icon}: 40×40px — meets WCAG AA 44×44 minimum, falls slightly short of AAA (recommend increasing to 44px for strict compliance)
• {component.button-icon-small}: 32×32px — below WCAG recommended minimum; acceptable only for secondary/tertiary actions in dense toolbars
• {component.category-chip}: ~36px height (8px padding × 2 + 20px text) — borderline; recommend min-height: 40px for mobile
• {component.text-input}: 44px height — meets WCAG AAA minimum ✓
• {component.carousel-nav-button}: 40×40px — same as button-icon, recommend 44px upgrade

Collapsing Strategy

• Navigation: Top nav remains persistent at all breakpoints but collapses horizontal links into a hamburger menu on mobile (< 640px), revealing a drawer/sheet on tap. Logo and cart icon remain visible always.
• Hero/carousel: Maintains full-width presentation at all sizes; internal padding reduces from 32px to 20px on mobile. Navigation arrows may hide on touch devices (swipe gesture replaces them) or shrink to 32px.
• Menu grid: Responsive column count (grid-cols-1 → sm:grid-cols-2 → md:grid-cols-3) ensures cards reflow naturally. Card padding may tighten from 24px to 16px on mobile.
• Category chips: Horizontal scrollable row (overflow-x-auto) on mobile with snap-scroll; wraps to multi-line or expands on tablet+.
• Modal/sheets: On mobile, modals render as bottom-sheets (slide up from bottom, full-width); on desktop, they center as floating panels with max-width constraint.
• Sticky elements: Cart bar, if implemented, sticks to viewport bottom on mobile (thumb-friendly zone) and top-right or top-fixed on desktop.

Image Behavior

• Carousel hero image: Circular crop (120px diameter on mobile, scales to ~160–180px on desktop) maintains aspect ratio within {component.skeleton-circle} placeholder. Should use object-fit: cover and border-radius: 50%.
• Menu card images: 4:3 or 16:9 landscape, object-fit: cover, clipped to {rounded.lg} (16px) corners. Height fixed (~180–220px) with width fluid; prevents layout shift with aspect-ratio CSS property.
• Logo: Scalable vector (SVG preferred) or high-res PNG with max-height constraint in nav. Reduces size on mobile nav (likely 28–32px height vs 36–40px desktop).
• Lazy loading: All below-fold images should use loading="lazy" + Intersection Observer; carousel images may preload first/next slides eagerly.

Iteration Guide

1. Build a landing page or ordering interface that closely mimics the design system in this DESIGN.md. Use Next.js with Tailwind CSS as the foundational stack, matching the detected architecture.

2. Pull every color, font, radius, and spacing value from the YAML frontmatter via the {section.token} paths defined in this file. Never hard-code a hex code, pixel value, or font-size that has a corresponding token—if you find yourself writing #03 anywhere, stop and use {colors.primary} instead.

3. Add state variants (-hover, -disabled, -focus, -active) per your stack's conventions; the spec documents Default and Active/Pressed/Focus states as separate frontmatter entries (e.g., {component.button-primary-active}, {component.text-input-focus}). Hover styling is your implementation decision based on these anchors.

4. When adding a new component, decide first which sub-system it belongs to: Carousel Dialect (showcase/promotional, rounded-xl containers, dot pagination), Menu Grid Dialect (card-based, 3-column responsive, category-filtered), Skeleton/Loading Dialect (shimmer-animated placeholders matching final geometry), or Chrome/Nav Dialect (glass backgrounds, sticky positioning, utility icons). Each sub-system has distinct radius, shadow, and spacing patterns.

5. Variants of an existing component live as separate top-level frontmatter entries, never nested. For example, {component.category-chip} and {component.category-chip-active} are siblings, not a component with a variants object. This keeps state machine logic flat and linter-friendly.

6. Run npx @google/design.md lint DESIGN.md after edits — broken-ref (token paths that don't resolve), contrast-ratio (accessibility failures between text/background pairs), and orphaned-tokens (tokens defined but never referenced in components or prose) warnings flag issues automatically.

7. Implement the skeleton system early—define {component.skeleton-line}, {component.skeleton-circle}, {component.skeleton-title}, and the shimmer keyframe animation before building real content. The skeleton shapes lock in your layout geometry and prevent shift-on-load jank.

8. When in doubt about visual emphasis: prefer larger type size ({typography.display-lg} over {typography.title-md}) before bolder weight; prefer {colors.primary} background on a button over adding a shadow or border; prefer the signature {rounded.pill} button shape over rectangular alternatives.

9. Maintain the glass nav pattern—use backdrop-blur + semi-transparent white backgrounds for {component.top-nav} and {component.top-nav-scrolled} rather than solid fills. This is a core depth cue that separates this design from flatter alternatives.

10. Test the responsive grid collapse aggressively: verify that grid-cols-1 sm:grid-cols-2 md:grid-cols-3 produces acceptable card layouts at 375px (iPhone SE), 768px (iPad portrait), and 1440px (desktop) viewports. Adjust {spacing.lg} card padding down to {spacing.md} on mobile if content feels loose.

Font Setup

Poppins is self-hosted in the current implementation via WOFF2 files with unicode-range splitting. For new implementations or prototyping, use Google Fonts:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700&display=swap" rel="stylesheet">

Define the CSS variable for consumption:

:root {
  --font-poppins: "Poppins", "Poppins Fallback", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
}

body {
  font-family: var(--font-poppins);
}

If Poppins cannot be loaded (offline environments, restrictive CSP), Nunito (Google Fonts) is the closest visual match—same geometric humanist classification, similar x-height and aperture proportions, identical weight range (400–700). Substitute by changing the font-family list order only; all spacing, size, and weight tokens remain unchanged.

Known Gaps

• Hover state styling: Per the no-hover policy, hover backgrounds, border changes, and transform lifts on buttons/cards/chips are not documented. Implement based on Active state direction (e.g., {component.button-primary-active} suggests hover should lighten toward {colors.primary-hover}).
• Loading/error/empty states beyond skeleton: No "no results found" illustration, network error state, or empty cart state was observable in the screenshot. Design these using {colors.muted} text, {typography.body-md}, and optional illustration in {colors.surface-soft}.
• Form validation states: Only {component.text-input-focus} is documented. Error state (red border {colors.error}, error message below) and disabled state (reduced opacity, {colors.surface-strong} background) require implementation decisions.
• Dark mode tokens: The extensions.mode is "dark" but the visual evidence strongly indicates a light-theme interface (white canvases, near-black text). If a true dark mode is planned, an inverted surface/text palette and adjusted shadow opacities will be needed—not covered here.
• Authenticated/user flows: Login modal, account dashboard, order history, and checkout pages were not visible. These may introduce new components (avatar, order-status-timeline, payment-method-card) beyond the current marketing/ordering scope.
• Pixel-exact skeleton dimensions: The 120px circle diameter and 20px/28px/12px skeleton heights are extracted from the specific screenshot frame; production skeleton sizes should match the actual loaded content dimensions, which may vary by carousel slide type.
• Accessibility focus indicators: Beyond the elevation table's focus-row specification, no custom focus-ring styles (outline offset, ring color, ring-width) were extractable. Implement following WCAG 2.4.11 with visible {colors.info} or {colors.primary} rings.
• Internationalization (i18n) layout: While Poppins includes Devanagari unicode-range support (suggesting Urdu capability), RTL layout considerations, translated string lengths, and script-specific line-height adjustments are not addressed.
• Animation timing functions: The extracted all transition uses ease (CSS default), but the 17 keyframe animations may use custom cubic-bezier or steps() timing not captured in the transition declaration. Inspect <style> block @keyframes rules for precise easing.
• Print styles: No @media print stylesheet or print-specific component variants (hiding nav, showing URLs, converting carousels to static grids) were detectable. Add if the site supports menu printing.