BelgianBitcoinEmbassy/context/design.md

Design System Specification: The Sovereign Editorial

1. Overview & Creative North Star

The "Sovereign Editorial" is the creative North Star for this design system. It moves away from the chaotic, high-frequency aesthetic of "crypto-hype" and instead leans into the quiet authority of a diplomatic institution. This is not a "trading platform"; it is an Embassy.

The system breaks the standard "web template" look by utilizing Intentional Asymmetry and Tonal Depth. We prioritize a high-end, editorial feel through expansive whitespace (using the 20 and 24 spacing tokens), overlapping elements that break the grid, and a typography scale that treats information as a curated exhibition rather than a data dump.

---

2. Colors: Tonal Depth & The "No-Line" Rule

The palette is rooted in a "Rich Black" foundation, using surface (#131313) as the canvas.

The "No-Line" Rule

Explicit Instruction: 1px solid borders for sectioning are strictly prohibited. Structure must be defined solely through:

• Background Shifts: Placing a surface-container-low section against a surface background.
• Negative Space: Using large gaps from the Spacing Scale (e.g., 12 or 16) to imply boundaries.

Surface Hierarchy & Nesting

Treat the UI as a series of physical layers, like stacked sheets of obsidian glass.

• Base Layer: surface (#131313)
• Secondary Sectioning: surface-container-low (#1c1b1b)
• Interactive/Floating Cards: surface-container-high (#2a2a2a)
• The "Glass & Gradient" Rule: For primary CTAs and hero highlights, use a subtle linear gradient from primary (#ffb874) to primary-container (#f7931a). Floating navigation or "pinned" elements must use surface-bright with a 15px backdrop-blur to create a premium glassmorphism effect.

---

3. Typography: Authority Through Scale

We use Inter (as the modern web equivalent to San Francisco) to provide a neutral, trustworthy foundation. The hierarchy is designed to feel like a high-end broadsheet.

• Display (The Statement): Use display-lg (3.5rem) for hero statements. Tighten letter-spacing to -0.02em for a "premium print" look.
• Headline (The Narrative): headline-lg (2rem) and headline-md (1.75rem) provide the educational structure.
• Body (The Education): body-lg (1rem) is the workhorse. We prioritize a line-height of 1.6 to ensure readability for long-form educational content.
• Labels (The Metadata): label-md (0.75rem) should be used in uppercase with 0.05em letter spacing for a technical, diplomatic feel.

---

4. Elevation & Depth: Tonal Layering

Traditional drop shadows are replaced by Ambient Occlusion and Material Stacking.

• The Layering Principle: To lift a card, do not add a shadow. Instead, place a surface-container-lowest (#0e0e0e) element inside a surface-container (#201f1f) section. The shift in value creates a natural perception of depth.
• Ambient Shadows: When a "floating" modal is necessary, use a blur of 40px with an 8% opacity of the on-surface color. It should feel like a soft glow rather than a harsh shadow.
• The "Ghost Border" Fallback: If accessibility requires a stroke (e.g., input fields), use outline-variant at 15% opacity. Never use 100% opaque borders.

---

5. Components

Buttons

• Primary: Gradient background (primary to primary_container), on-primary text. Shape: md (0.75rem) corner radius.
• Secondary: surface-container-highest background with on-surface text. No border.
• Tertiary: Text-only using primary_fixed_dim, strictly for low-priority actions.

Cards & Lists

• The Divider Ban: Dividers are forbidden. Separate list items using spacing-4 (1.4rem) of vertical whitespace or by alternating background colors between surface-container-low and surface-container-lowest.
• Cards: Always use rounded-lg (1rem). Content should have a minimum internal padding of spacing-6 (2rem).

Input Fields

• State: Background should be surface-container-highest.
• Focus: Transition the "Ghost Border" from 15% to 40% opacity of the primary color. Do not use heavy glow effects.

Signature Components for the Embassy

• The "Knowledge Card": A large-format card using surface-container-low with an asymmetrical layout—typography pushed to the left, and a subtle, desaturated Bitcoin icon overlapping the right edge at 5% opacity.
• The "Trust Indicator": A persistent, glassmorphic "Status" bar at the bottom of mobile screens, providing real-time network reassurance without cluttering the main content.

---

6. Do’s and Don’ts

Do:

• Use "Aggressive" Whitespace: If a section feels "almost right," double the padding.
• Embrace Asymmetry: Align headings to the left while keeping body text centered in a narrower column to create visual interest.
• Mobile-First Layering: On mobile, stack containers vertically, using surface-container-lowest to "ground" the footer.

Don’t:

• Don’t use "Crypto-Green/Red": Use error (#ffb4ab) sparingly for critical warnings only. Educational growth is signaled by Bitcoin Orange, not "Stock Market Green."
• Don’t use Dividers: If you need a line to separate content, you have failed to use the Spacing Scale correctly.
• Don’t Over-Animate: Transitions should be "Snappy & Subtle" (200ms ease-out). Avoid bouncing or heavy staggered entrances.