odoo_loyalty_app/DESIGN.md

Design System Strategy: Heritage Gallery Editorial

1. Overview & Creative North Star

The Creative North Star for this design system is "The Modern Curator." We are not building a standard utility app; we are designing a digital gallery that honors a rich culinary heritage through a modern, high-end editorial lens.

To achieve this, we move beyond the rigid "bootstrap" look. We break the template by embracing Intentional Asymmetry—where whitespace is as much a design element as the content itself. Overlapping elements, such as images bleeding off the edge or overlapping surface containers, create a sense of physical depth. By utilizing the Plus Jakarta Sans typeface at extreme scale contrasts, we establish an authoritative yet welcoming voice that feels premium, bespoke, and intentional.

---

2. Colors

Our palette is rooted in the warmth of tradition but executed with modern precision.

The Palette

• Primary (#E1251B): A bold, vibrant red used for high-impact CTAs and core brand moments.
• Secondary (#FFBF3C): A warm gold, used to draw attention to interactive accents and "Mapan" highlights.
• Tertiary (#CA8342): An earthy, wood-tone brown used for sophisticated detailing and organic warmth.
• Background (#EADFD2): A soft, parchment-like neutral that provides the "gallery wall" for our content.

The "No-Line" Rule

Explicit Instruction: Do not use 1px solid borders to section off content. Traditional lines are "noise" that clutter the heritage aesthetic. Boundaries must be defined solely through background color shifts. For example, a surface-container-low section should sit directly on a surface background to define its territory.

Surface Hierarchy & Nesting

Treat the UI as a series of physical layers—stacked sheets of fine paper.

• Use the Surface Tiers (surface-container-lowest to highest) to create depth.
• Nesting: An inner card should be surface-container-lowest (pure white) when placed on a surface-container-low section. This creates a soft, natural "lift" without the need for artificial borders.

The "Glass & Gradient" Rule

To add "soul" to the interface:

• Glassmorphism: Use semi-transparent versions of surface colors with a backdrop-blur for floating navigation bars or modal overlays.
• Signature Gradients: Use subtle transitions from primary (#BB0004) to primary-container (#E1251B) on large buttons or Hero backgrounds. This prevents the "flat-web" look and adds professional polish.

---

3. Typography

We use Plus Jakarta Sans to balance contemporary geometric shapes with warm, humanistic curves.

• Display Scale (display-lg to sm): Used for "Hero" moments and editorial storytelling. Use extreme negative letter-spacing (-0.02em) to create a high-fashion, compact look.
• Headline & Title Scale: These are your signposts. Use headline-lg for section headers with generous top-padding to let the "curation" breathe.
• Body & Labels: body-lg (1rem) is our standard for readability. Use label-md for metadata, ensuring high contrast using the on-surface-variant token.

The hierarchy is designed to be Editorial First: large headings should feel like magazine titles, while body text provides the "curator's notes" in a clean, legible block.

---

4. Elevation & Depth

In this design system, depth is felt, not seen. We favor Tonal Layering over structural shadows.

The Layering Principle

Depth is achieved by "stacking" the surface-container tiers. For instance, a floating action card should use surface-container-lowest to pop against a surface-dim background.

Ambient Shadows

When a physical "lift" is required (e.g., a floating bottom sheet):

• Diffusion: Shadows must be extra-diffused (Blur: 20px-40px).
• Opacity: Keep opacity between 4% and 8%.
• Tinting: Never use pure black. Tint the shadow with on-surface (#201B13) to mimic natural, ambient light reflecting off the heritage wood tones.

The "Ghost Border" Fallback

If accessibility requires a container edge, use a Ghost Border: the outline-variant token at 15% opacity. Standard 100% opaque borders are strictly forbidden.

---

5. Components

Buttons

• Primary: primary background with on-primary text. Apply a xl (0.75rem) roundedness for a modern, tactile feel.
• Secondary: secondary-container (#FEBE3B) with on-secondary-container. This acts as a "warm" alternative for secondary actions.
• Glass Variant: For buttons sitting on imagery, use a semi-transparent surface with a heavy blur.

Cards & Lists

• No Dividers: Forbid the use of horizontal rules. Separate list items using the Spacing Scale (e.g., spacing-4) or by alternating between surface and surface-container-low.
• Imagery: Cards should feature high-quality photography that bleeds to the top and sides, emphasizing the "Gallery" aesthetic.

Chips & Inputs

• Chips: Use surface-container-high for unselected states and tertiary for selected states.
• Input Fields: Use a "minimalist-underlined" or "soft-filled" style. Forbid the heavy "boxed" input. The background should be surface-container-lowest.

Signature Component: The "Heritage Overlay"

A specific component for this system: An image container with a tertiary-container (#A56526) accent tab in the corner, holding a label-sm tag. This mimics the labeling of artifacts in a gallery.

---

6. Do's and Don'ts

Do

• Do use intentional white space. If you think a section needs more room, double the spacing.
• Do overlap elements. Let a product image break the container of a card to create 3D interest.
• Do use the tertiary wood-tones for subtle accents like icons or small labels to tie into the "Heritage" material.

Don't

• Don't use 1px solid black or grey borders. This immediately destroys the "Modern Gallery" feel.
• Don't use standard drop shadows. If it looks like a "box shadow," it’s too heavy.
• Don't crowd the layout. If the user feels overwhelmed, the "Curator" has failed.
• Don't use pure black (#000000) for text. Use on-surface (#201B13) to keep the typography feeling organic and soft.