Design System & UI

🎨 Design System & UI

Living Document - Questo documento definisce il linguaggio visivo “Dark Forest” dell’ecosistema BlackTrails.

🌲 Philosophy: Dark Forest Identity

Il design system BlackTrails si ispira alla foresta notturna:

• Profondità: Sfumature di nero e verde scuro per immersione totale
• Bioluminescenza: Accenti verdi brillanti come muschio fosforescente
• Glassmorphism: Superfici traslucide con blur per effetto “rugiada”
• Organicità: Transizioni fluide e curve naturali (no angoli duri)

Ispirazione: Tolkien (Middle-earth forests), The Matrix (green glow), Blade Runner 2049 (atmospheric depth)

---

🎨 Color Palette

Primary Colors (Forest Dark)

/* Scala di Grigi Forestali */
--sl-color-white: #ffffff;          /* Testo principale (alto contrasto) */
--sl-color-gray-1: #eef2eb;         /* Testo enfatizzato */
--sl-color-gray-2: #c5d1c0;         /* Testo chiaro, lead paragraphs */
--sl-color-gray-3: #8ba185;         /* Testo secondario verdastro */
--sl-color-gray-4: #4a5c45;         /* Footer, meta info */
--sl-color-gray-5: #2d382b;         /* Bordi sottili */
--sl-color-gray-6: #1a2119;         /* Sfondo card */
--sl-color-black: #0a0c0a;          /* Sfondo profondo */

Accent Colors (Bioluminescent Green)

/* Verde Foresta Bioluminescente */
--sl-color-accent-low: #1e3a12;     /* Sfondo selezione, hover states */
--sl-color-accent: #4a7c23;         /* Colore principale brand */
--sl-color-accent-high: #76c44e;    /* Hover brillante, link attivi */

Utilizzo:

• accent-low: Background per stati hover/focus
• accent: Primary action buttons, borders attivi
• accent-high: Link hover, glow effects

Semantic Colors

/* Badge & Alert Colors */
--color-success: #4a7c23;   /* (Same as accent) */
--color-danger: #d9534f;    /* Errori critici */
--color-warning: #f0ad4e;   /* Attenzione */
--color-info: #5bc0de;      /* Informazioni */
--color-note: #8ba185;      /* Note secondarie */

---

📝 Typography

Font Families

/* System Font Stack (Body & UI) */
--bt-font-stack: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;

/* Code & Monospace */
--sl-font-mono: 'JetBrains Mono', monospace;

Loaded Fonts:

• Inter (400, 600, 800): Body text, headings, UI
• JetBrains Mono (400): Code blocks, terminal output

Font Sizes & Hierarchy

Element	Size	Weight	Usage
Hero H1	3rem (48px)	800	Homepage hero titles
H1	2.25rem (36px)	800	Page titles (hidden, used for SEO)
H2	1.875rem (30px)	700	Section titles
H3	1.5rem (24px)	600	Subsection titles
H4	1.25rem (20px)	600	Card titles
Body	1rem (16px)	400	Paragraph text
Lead	1.125rem (18px)	400	First paragraph (intro)
Small	0.875rem (14px)	400	Meta info, captions
Code	0.9em	400	Inline code

Typography Rules

/* Content Readability */
.sl-markdown-content {
  max-width: 85ch;        /* Optimal reading width */
  line-height: 1.8;       /* Generous line height */
}

/* Lead Paragraph (First <p>) */
.sl-markdown-content > p:first-of-type {
  font-size: 1.125rem;    /* 18px - Slightly larger */
  color: var(--sl-color-gray-2);
  margin-bottom: 2rem;
  line-height: 1.6;
}

/* Hero Gradient Text */
.hero h1 {
  font-weight: 800;
  letter-spacing: -0.03em;  /* Tight tracking for display text */
  background: linear-gradient(180deg, #ffffff 0%, #a3bba3 100%);
  background-clip: text;
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  filter: drop-shadow(0 0 20px rgba(74, 124, 35, 0.3)); /* Green glow */
}

---

🧩 Core Components

1. Cards (Glassmorphism)

Style:

.card {
  background: rgba(20, 20, 20, 0.6);
  border: 1px solid rgba(255, 255, 255, 0.08);
  backdrop-filter: blur(10px);
  border-radius: 12px;
  padding: 1.5rem;
  transition: all 0.5s cubic-bezier(0.22, 1, 0.36, 1); /* Organic easing */
}

.card:hover {
  transform: translateY(-4px);
  border-color: var(--sl-color-accent);
  box-shadow: 0 12px 40px -10px rgba(74, 124, 35, 0.3); /* Green glow */
}

Usage:

• Philosophy cards (homepage)
• Brand ecosystem cards
• Documentation feature cards

2. Buttons

Primary Action:

.action.primary {
  background: var(--sl-color-accent);
  color: #fff;
  border: none;
  border-radius: 8px;
  padding: 0.75rem 1.5rem;
  font-weight: 600;
  box-shadow: 0 0 15px rgba(74, 124, 35, 0.4);
  transition: box-shadow 0.3s ease;
}

.action.primary:hover {
  box-shadow: 0 0 25px rgba(118, 196, 78, 0.6); /* Intensified glow */
}

Secondary Action:

.action.secondary {
  background: transparent;
  color: var(--sl-color-accent-high);
  border: 1px solid var(--sl-color-accent);
  border-radius: 8px;
  padding: 0.75rem 1.5rem;
  font-weight: 600;
}

.action.secondary:hover {
  background: rgba(74, 124, 35, 0.1);
}

3. Links

.sl-markdown-content a {
  color: var(--sl-color-accent-high);
  text-decoration: none;
  border-bottom: 1px solid transparent;
  transition: border-color 0.2s ease;
}

.sl-markdown-content a:hover {
  border-bottom-color: var(--sl-color-accent-high);
}

4. Blockquotes

blockquote {
  border-left: 3px solid var(--sl-color-accent);
  background: rgba(74, 124, 35, 0.05);
  padding: 1rem 1.5rem;
  margin: 1.5rem 0;
  font-style: italic;
  color: var(--sl-color-gray-2);
  border-radius: 0 8px 8px 0;
}

Usage:

• Philosophical quotes (Rhama, manifesto)
• Important notes
• Pull quotes

5. Code Blocks

pre {
  background: rgba(0, 0, 0, 0.3);
  border: 1px solid rgba(255, 255, 255, 0.05);
  border-radius: 8px;
  padding: 1rem;
  overflow-x: auto;
}

code {
  font-family: var(--sl-font-mono);
  font-size: 0.9em;
  color: var(--sl-color-gray-1);
}

---

🌊 Effects & Animations

1. Glassmorphism (Navbar)

header {
  background-color: rgba(10, 12, 10, 0.7);
  backdrop-filter: blur(12px);
  border-bottom: 1px solid rgba(255, 255, 255, 0.05);
}

Effect: Translucent navbar with background blur, floating sensation

2. Atmospheric Background

body {
  background: radial-gradient(
    circle at 50% -20%,
    #1a2e12 0%,    /* Green glow from top */
    #050505 50%,   /* Fade to deep black */
    #000000 100%   /* Pure black at bottom */
  );
  background-attachment: fixed;
}

Effect: Creates depth with light emanating from above (like moonlight through forest canopy)

3. Hover Transitions

Organic Easing:

transition: all 0.5s cubic-bezier(0.22, 1, 0.36, 1);

Usage:

• Card hover states (lift + glow)
• Button hover (glow intensification)
• Link underline (border-bottom slide)

4. Glow Effects (Box Shadow)

/* Subtle Glow (Default) */
box-shadow: 0 0 15px rgba(74, 124, 35, 0.4);

/* Intense Glow (Hover) */
box-shadow: 0 0 25px rgba(118, 196, 78, 0.6);

/* Card Shadow (Elevation) */
box-shadow: 0 12px 40px -10px rgba(74, 124, 35, 0.3);

---

📐 Layout & Spacing

Container Widths

/* Content Reading Width */
--sl-content-width: 60rem; /* 960px (increased from default 45rem) */

/* Markdown Content Max Width */
.sl-markdown-content {
  max-width: 85ch; /* ~1360px at 16px font */
}

/* Full Width for Diagrams & Tables */
.sl-markdown-content .mermaid,
.sl-markdown-content table,
.sl-markdown-content pre {
  max-width: 100%; /* Use full container width */
}

Breakpoints

/* Mobile First Approach */
--bt-breakpoint-mobile: 50rem;   /* 800px */
--bt-breakpoint-tablet: 48rem;   /* 768px */

Border Radius

--sl-border-radius-medium: 12px;  /* Cards, buttons, modals */
--sl-border-radius-small: 8px;    /* Code blocks, badges */

---

🔧 Special Features

1. Dark Mode (Forced)

/* Hide theme toggle - Dark mode only */
starlight-theme-select {
  display: none !important;
}

Reasoning: Forest identity requires dark immersion (no light mode)

2. Active Link Styling (Sidebar)

a[aria-current="page"] {
  color: var(--sl-color-accent-high);
  background: rgba(74, 124, 35, 0.1);
  border-left: 3px solid var(--sl-color-accent);
}

3. Search Box

.search-input {
  background: rgba(255, 255, 255, 0.05);
  border: 1px solid rgba(255, 255, 255, 0.1);
}

.search-input:focus {
  border-color: var(--sl-color-accent);
  box-shadow: 0 0 10px rgba(74, 124, 35, 0.2);
}

4. Footer Signature

footer::after {
  content: "2025 BlackTrails · 🌲";
  display: block;
  text-align: center;
  margin-top: 2rem;
  font-size: 0.8rem;
  color: var(--sl-color-gray-4);
  opacity: 0.6;
}

---

🎭 Homepage Special Rules

Full Width Layout (No Sidebars)

/* Hide sidebars on homepage only */
body.is-home .sidebar-pane,
body.is-home .right-sidebar-container {
  display: none !important;
}

/* Allow full viewport width */
body.is-home .sl-markdown-content {
  max-width: 100% !important;
  padding: 0 !important;
}

Card Grid Layout

.card-grid {
  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
}

/* Desktop: 4 columns for ecosystem cards */
@media (min-width: 48rem) {
  .card-grid {
    grid-template-columns: repeat(4, 1fr);
  }
}

---

🤖 Agent Update Instructions

AI Assistant: Quando il design system cambia (nuovi colori, componenti, effetti), esegui:

# 1. Analizza i file CSS
read_file E:\blacktrails-docs\src\styles\custom.css
read_file E:\blacktrails-docs\astro.config.mjs

# 2. Aggiorna questo file mantenendo:
#    - Palette colori (se cambiano variabili CSS)
#    - Nuovi componenti (card variants, buttons, etc.)
#    - Effetti aggiunti (glassmorphism, glow, animations)
#    - Breakpoints e layout rules

# 3. Mantieni esempi CSS chiari e funzionali

# 4. Commit con messaggio:
git commit -m "docs(truth): update design system"

---

Last Auto-Update: 2025-12-21
Next Review: On design token change
Maintainer: BlackTrails AI Agent
Figma (Future): [Design System Source File]
CSS Source: src/styles/custom.css