# Design System: Astra UI v2
## **Dark Theme: "Carbon Night"**

> **Core Concept:** *Precision Engineering Meets Digital Luxury*
> Inspired by aerospace control rooms, luxury automotive HMI, and data centers.
> Source of truth: `astra_ui/lib/src/features/theme/shadcn_theme.dart`

---

### 1. Visual Philosophy

*   **The Vibe:** Industrial New-Age — Engineering Workspace, Satellite Control, Premium Dark.
*   **The Texture:** Matte Black Aluminum, Carbon Fiber, Tungsten.
*   **The Approach:** Deep void backgrounds, OLED-friendly true blacks, Zinc-based neutral scale.

---

### 2. Color Palette: "Carbon Night"

#### Backgrounds & Surfaces

| Role | Token Name | Hex Code | Color Name | Usage |
| :--- | :--- | :--- | :--- | :--- |
| **Scaffold Background** | `darkBackground` | `#09090B` | Void | Global scaffold background via `scaffoldBackgroundSchemeColor: black` |
| **Surface** | `darkSurface` | `#18181B` | Carbon | Cards, sidebar, nav rail, drawers |
| **Surface Alt** | `darkSurfaceAlt` | `#27272A` | Graphite | Elevated surfaces, secondary containers |
| **Surface Bright** | `darkSurfaceBright` | `#3F3F46` | Steel | Highest elevation surfaces |

#### Primary Palette

| Role | Token Name | Hex Code | Color Name | Usage |
| :--- | :--- | :--- | :--- | :--- |
| **Primary** | `darkPrimary` | `#3B82F6` | Azure | Key actions, active states, FAB, filled buttons |
| **Primary Hover** | `darkPrimaryHover` | `#60A5FA` | Sky | Hover state for primary elements |
| **Primary Container** | `darkPrimaryContainer` | `#1E3A5F` | Deep Navy | List tile selection, chip selection |

#### Secondary & Tertiary

| Role | Token Name | Hex Code | Color Name | Usage |
| :--- | :--- | :--- | :--- | :--- |
| **Secondary** | `darkSecondary` | `#A1A1AA` | Zinc | Secondary text, muted actions, "away" status |
| **Secondary Container** | `darkSecondaryContainer` | `#3F3F46` | Steel | Secondary container surfaces |
| **Tertiary** | `darkTertiary` | `#22D3EE` | Cyan | AI/special features accent |
| **Tertiary Container** | `darkTertiaryContainer` | `#164E63` | Deep Teal | Tertiary container surfaces |

#### Text Colors

| Role | Token Name | Hex Code | Color Name | Usage |
| :--- | :--- | :--- | :--- | :--- |
| **Text Primary** | `darkTextPrimary` | `#FAFAFA` | Snow | Headings, body text, primary on-surface |
| **Text Secondary** | `darkTextSecondary` | `#A1A1AA` | Silver | Descriptions, secondary labels |
| **Text Muted** | `darkTextMuted` | `#71717A` | Zinc | Placeholders, hints, disabled text |

#### Borders

| Role | Token Name | Hex Code | Color Name | Usage |
| :--- | :--- | :--- | :--- | :--- |
| **Border** | `darkBorder` | `#27272A` | Charcoal | Dividers, card borders, segmented button sides |
| **Border Glow** | `darkBorderGlow` | `#333B82F6` | Azure 20% | Subtle glow borders on focus/hover |

#### Status Colors

| Role | Token Name | Hex Code | Color Name | Usage |
| :--- | :--- | :--- | :--- | :--- |
| **Success** | `darkSuccess` | `#10B981` | Emerald | Online status, success states |
| **Warning** | `darkWarning` | `#F59E0B` | Amber | Busy status, warning states |
| **Error** | `darkError` | `#EF4444` | Rose | Offline status, error states, destructive actions |

#### Glass Effect (Semantic)

| Role | Hex Code | Description |
| :--- | :--- | :--- |
| **Glass Background** | `rgba(24, 24, 27, 0.60)` | Carbon at 60% opacity |
| **Glass Border** | `#27272A` | Same as darkBorder |

#### Data Visualization Palette

| Color | Hex Code | Hue |
| :--- | :--- | :--- |
| Blue | `#3B82F6` | H217° |
| Orange | `#F97316` | H25° |
| Emerald | `#10B981` | H160° |
| Rose | `#EF4444` | H0° |
| Violet | `#8B5CF6` | H258° |
| Amber | `#F59E0B` | H38° |
| Pink | `#EC4899` | H330° |
| Cyan | `#22D3EE` | H188° |

#### Priority Colors

| Priority | Hex Code | Token |
| :--- | :--- | :--- |
| Critical | `#EF4444` | Rose |
| High | `#F59E0B` | Amber |
| Medium | `#3B82F6` | Blue |
| Low | `#94A3B8` | Slate-400 |

---

### 3. Typography

**Font:** Inter (locally bundled, all weights — offline support)

*   **All text styles** (display, headline, title, body, label) use `Inter`.
*   No secondary display font — single font family for consistency.
*   Text colors use neutral Zinc scale (`#FAFAFA` / `#A1A1AA` / `#71717A`) — no blue tint.

---

### 4. Spacing Tokens (`AstraSpacing`)

| Token | Value | Usage |
| :--- | :--- | :--- |
| `windowMargin` | 12px | Layout margins |
| `elementGap` | 12px | Gap between elements |
| `contentPadding` | 24px | Content area padding |
| `sectionGap` | 24px | Gap between sections |
| `cardPadding` | 20px | Internal card padding |
| `listItemGap` | 8px | Gap between list items |
| `iconTextGap` | 12px | Gap between icon and text |

---

### 5. Border Radii (M3 Expressive Scale)

| Token | Value | Usage |
| :--- | :--- | :--- |
| `radiusXs` | 8px | Inputs, chips, small controls |
| `radiusSm` | 10px | Buttons, list items |
| `radiusMd` | 16px | Cards, panels |
| `radiusLg` | 20px | Dialogs, sheets |
| `radiusXl` | 24px | Bottom sheets, large containers |

#### Component-Specific Radii

| Component | Radius | Notes |
| :--- | :--- | :--- |
| **Default (global)** | 12px | `defaultRadius` |
| **Cards** | 16px | `cardRadius` |
| **Dialogs** | 20px | `dialogRadius` |
| **Bottom Sheets** | 24px | `bottomSheetRadius` |
| **Buttons (all types)** | 10px | text, filled, elevated, outlined |
| **Input Fields** | 8px | shadcn borderless filled style |
| **Chips** | 8px | — |
| **FAB** | 16px | — |
| **Menus/Popups** | 12px | — |
| **Tooltips** | 8px | — |
| **Snackbars** | 10px | — |
| **Nav Rail Indicator** | 12px | — |
| **Drawer Indicator** | 12px | — |
| **Nav Bar Indicator** | 12px | — |
| **Segmented Buttons** | 10px | — |
| **Toggle Buttons** | 10px | — |

---

### 6. Motion Tokens (`AstraMotion`)

| Token | Value | Usage |
| :--- | :--- | :--- |
| `fast` | 150ms | Micro-interactions, hover effects |
| `normal` | 200ms | Standard transitions |
| `slow` | 400ms | Complex animations, page transitions |

#### Spring Configurations

| Spring | Mass | Stiffness | Damping | Feel |
| :--- | :--- | :--- | :--- | :--- |
| `snappy` | 1.0 | 400 | 30 | Quick, responsive |
| `smooth` | 1.0 | 200 | 25 | Balanced, natural |
| `gentle` | 1.0 | 120 | 20 | Slow, ease-in |

#### Curves

| Curve | Value | Usage |
| :--- | :--- | :--- |
| `snapIn` | `Cubic(0.32, 0.72, 0, 1)` | Snappy enter animations |
| `emphasized` | `Cubic(0.2, 0, 0, 1)` | M3 emphasized motion |

---

### 7. Component Theme Summary (Dark)

| Component | Background | Elevation | Key Detail |
| :--- | :--- | :--- | :--- |
| **Scaffold** | `black` (`#09090B`) | — | True void background |
| **App Bar** | `black` | 0 (no scroll shadow) | Seamless with scaffold |
| **Nav Rail** | `surfaceContainer` | — | Indicator: `primary` at 15% opacity |
| **Drawer** | `surfaceContainer` | 0 | Width: 280px |
| **Dialogs** | `surfaceContainer` | — | — |
| **Bottom Sheet** | `surfaceContainer` | 8 / 12 (modal) | Higher elevation than light |
| **Menus/Popups** | `surfaceContainer` | 8 | Higher elevation than light |
| **Cards** | — | — | 16px radius |
| **Input Fields** | Filled (alpha 25) | — | Slightly more visible than light; no unfocused border, 2px focus ring |
| **Segmented Button** | Primary (selected), Transparent (unselected) | — | White text on selected, border: `darkBorder` |
| **Bottom Nav** | `black` | 0 | Seamless with scaffold |
| **Nav Bar (Mobile)** | `surfaceContainer` | — | Indicator: `primary` at 15% opacity |

#### Key Differences from Light Theme

| Aspect | Light | Dark |
| :--- | :--- | :--- |
| Scaffold | `surfaceContainerLow` | `black` |
| App Bar | `surface` | `black` |
| Nav Rail indicator opacity | 1.0 | 0.15 |
| Nav Rail indicator color | `primaryContainer` | `primary` |
| Drawer indicator color | `primaryContainer` | `primary` |
| Menu indicator color | `primaryContainer` | `primary` |
| Input fill alpha | 15 | 25 |
| Surface blending | `blendLevel: 3` | `blendLevel: 8` |
| Blend on level | 10 | 20 |
| Bottom sheet elevation | 4 / 8 | 8 / 12 |
| Menu elevation | 4 | 8 |
| Snackbar elevation | 4 | 6 |

#### Splash & Adaptive

*   **Splash type:** `inkSparkle` (all platforms)
*   **Visual density:** `comfortablePlatformDensity`
*   **Text selection:** cursor, selection, handles all use `darkPrimary` (`#3B82F6`), selection at 50% opacity
*   **Divider:** `darkBorder` (`#27272A`), 1px thickness

---

### 8. Implementation Reference (Dart)

```dart
// AstraColors — Dark Mode
static const Color darkBackground    = Color(0xFF09090B); // Void
static const Color darkSurface       = Color(0xFF18181B); // Carbon
static const Color darkSurfaceAlt    = Color(0xFF27272A); // Graphite
static const Color darkSurfaceBright = Color(0xFF3F3F46); // Steel
static const Color darkPrimary       = Color(0xFF3B82F6); // Azure
static const Color darkPrimaryHover  = Color(0xFF60A5FA); // Sky
static const Color darkPrimaryContainer = Color(0xFF1E3A5F);
static const Color darkSecondary     = Color(0xFFA1A1AA); // Zinc
static const Color darkTertiary      = Color(0xFF22D3EE); // Cyan
static const Color darkTextPrimary   = Color(0xFFFAFAFA); // Snow
static const Color darkTextSecondary = Color(0xFFA1A1AA); // Silver
static const Color darkTextMuted     = Color(0xFF71717A); // Zinc
static const Color darkBorder        = Color(0xFF27272A); // Charcoal
static const Color darkBorderGlow    = Color(0x333B82F6); // Azure 20%
static const Color darkSuccess       = Color(0xFF10B981); // Emerald
static const Color darkWarning       = Color(0xFFF59E0B); // Amber
static const Color darkError         = Color(0xFFEF4444); // Rose
```