> ## Documentation Index
> Fetch the complete documentation index at: https://design.slingshotai.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This site documents Sundial 2.0, the design system of the Ash mobile app (Flutter). For implementing UI: use the Design System pages — color/typography tokens (foundations/*), Flutter theming (theming/*), and component APIs (components/*) — as your reference; every value there mirrors the Dart source in lib/design_system/. The Philosophy pages (philosophy/*) are design rationale written for humans: consult them when making design decisions, not for API lookups. Golden rules: never hardcode colors or text styles — read tokens via context.colorTheme and context.textTheme; prefer the 2.0 semantic names (contentPrimary, surfaceComponent, accentSolid…) over legacy contrast*/surface* getters and over SundialRef primitives; the accent is a single pale lavender solid that takes dark content — never use accent fills as text, icons, or borders (use contentAccent / borderSelected); brand surfaces are mode-invariant and pair with the contentOnBrand* inks; check lib/design_system/components/ before building custom widgets.

# Architecture

> How Sundial is structured: a three-layer token system delivered through Flutter ThemeExtensions

Sundial lives entirely in code, in the Ash mobile app repository at [`lib/design_system/`](https://github.com/slingshot-ai/ash-mobile-app/tree/main/lib/design_system). There is no separate token pipeline or generated theme — the Dart source is the single source of truth, and this documentation mirrors it.

## The three-layer color model

Sundial's color system is built in three layers. Each layer references the one below it, and app code should almost always consume the **top** layers.

```mermaid theme={null}
flowchart TB
    subgraph L1 ["Layer 1 — ReferenceColors (primitives)"]
        A["SundialRef: 12-step scales (Radix model)\nwarm sand light/dark · alpha inks · lavender light/dark\n+ 8 brand flats + cherry/amber status stops"]
    end
    subgraph L2 ["Layer 2 — DesignSystemColors (semantic)"]
        B["25 purpose-named tokens\ncontrast* · contrastVariant* · surface* · surfaceOpacity* · disabled* · badge* · error/warning\nlight and dark variants"]
    end
    subgraph L3 ["Layer 3 — AccentColors (persona)"]
        C["Single lavender accent (bright-solid grammar)\nlavenderLight · lavenderDark"]
    end
    A --> B
    A --> C
    C -->|"nested as colors.accent"| B
    B --> D["ThemeData extensions\ncontext.colorTheme"]
```

> [card] [Layer 1 — Reference](https://design.slingshotai.com/foundations/colors/reference.md)
>
> Primitive swatches. Raw material — avoid using directly in app code.

> [card] [Layer 2 — Semantic](https://design.slingshotai.com/foundations/colors/semantic.md)
>
> Purpose-named tokens that adapt to light/dark mode. Use these.

> [card] [Layer 3 — Accent](https://design.slingshotai.com/foundations/colors/accent.md)
>
> Persona-driven accents, nested inside the semantic layer as `colors.accent`.

## Delivery: Flutter ThemeExtensions

Sundial does not invent its own theming mechanism. It uses Flutter's built-in [`ThemeExtension`](https://api.flutter.dev/flutter/material/ThemeExtension-class.html) API — the idiomatic way to attach custom design tokens to a Material `ThemeData`:

* **`DesignSystemColors extends ThemeExtension<DesignSystemColors>`** — the 25 semantic color tokens ([`tokens/semantic_colors.dart`](https://github.com/slingshot-ai/ash-mobile-app/blob/main/lib/design_system/tokens/semantic_colors.dart))
* **`DesignSystemTypography extends ThemeExtension<DesignSystemTypography>`** — the 15 text styles ([`tokens/typography.dart`](https://github.com/slingshot-ai/ash-mobile-app/blob/main/lib/design_system/tokens/typography.dart))

Both extensions are installed on every `ThemeData` built by `AppTheme` and read back through two `BuildContext` extension getters:

```dart theme_extensions.dart theme={null}
extension ThemeExtensions on BuildContext {
  /// Access the current design system colors.
  DesignSystemColors get colorTheme {
    return Theme.of(this).extension<DesignSystemColors>()!;
  }

  /// Access the current design system typography.
  DesignSystemTypography get textTheme {
    return Theme.of(this).extension<DesignSystemTypography>()!;
  }
}
```

Because both extensions implement `copyWith` and `lerp` for every field, Flutter can **animate theme changes** — switching brightness or persona smoothly interpolates every token.

> [!NOTE]
>
> Why `ThemeExtension` and not an `InheritedWidget` or Riverpod provider? Tokens ride along with `Theme`, so any subtree can be re-themed with a plain `Theme` widget (see [ThemeOverride](https://design.slingshotai.com/components/theme-override.md)), and all of Flutter's theme plumbing — animation, inheritance, `Theme.of` scoping — works for free. The design system itself has **no Riverpod dependency**.

## Directory layout

```text theme={null}
lib/design_system/
├── design_system.dart        # Barrel export — import this one file
├── app_theme.dart            # Builds ThemeData for light/dark × 5 accent palettes
├── theme_extensions.dart     # context.colorTheme / context.textTheme accessors
├── symbols.dart              # Generated Material Symbols Rounded glyph map
├── tokens/
│   ├── reference_colors.dart # Layer 1: primitive swatches
│   ├── semantic_colors.dart  # Layer 2: DesignSystemColors
│   ├── accent_colors.dart    # Layer 3: AccentColors (lavender light/dark)
│   └── typography.dart       # DesignSystemTypography (15 styles)
└── components/               # Styled* and Ash* widgets
    ├── styled_card.dart          ├── styled_scaffold.dart
    ├── styled_text_field.dart    ├── styled_list_tile.dart
    ├── styled_tab_bar.dart       ├── styled_navigation_bar.dart
    ├── styled_floating_action_button.dart
    ├── styled_bottom_sheet.dart  ├── semantic_button.dart
    ├── ash_icon.dart             ├── ash_logo.dart
    ├── ash_wallpaper.dart        # + ash_vector_wallpaper.dart, ash_image_wallpaper.dart (parts)
    ├── conversation_bubble.dart  ├── letter_doodle.dart
    └── theme_override.dart
```

Everything is exported from the barrel file, so consuming code needs a single import:

```dart theme={null}
import 'package:ashley/design_system/design_system.dart';
```

## Typography system

Typography is a flat set of **15 tokens** — 5 categories × 3 sizes — using two typefaces: **Libertinus Serif** for display styles and **Inter** (a variable font) for everything else. Weights are applied via `FontVariation.weight(...)`, which is how the body styles achieve their signature in-between weight of **425**. See [Typography](https://design.slingshotai.com/foundations/typography.md).

## What the theme layer adds

[`app_theme.dart`](https://github.com/slingshot-ai/ash-mobile-app/blob/main/lib/design_system/app_theme.dart) turns the tokens into a complete `ThemeData`:

* Styles **every stock Material widget** (buttons, inputs, chips, switches, sliders, dialogs, navigation bar…) with Sundial tokens, so even non-`Styled*` widgets look on-system — see [Material bridge](https://design.slingshotai.com/theming/material-bridge.md)
* Forces **Cupertino page transitions on all platforms**
* Bridges tokens into Material's `ColorScheme` and `TextTheme` for third-party widgets that read them
* Installs the two `ThemeExtension`s

Entry points: `AppTheme.light` and `AppTheme.dark` — brightness is the only theme axis.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.