> ## 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.

# Conventions

> The naming, structure, and usage rules that keep Sundial coherent

## Naming prefixes

| Prefix | Meaning | Examples |
| - | - | - |
| `Styled*` | Design-system wrapper around a Material widget, injecting Sundial styling and behavior | `StyledCard`, `StyledScaffold`, `StyledTextField`, `showStyledBottomSheet` |
| `Ash*` | Brand-specific visual primitive with no Material counterpart | `AshIcon`, `AshLogo`, `AshWallpaper` |

## The variant pattern

Components encode variants as a **private enum + named constructors**, never a public `variant` parameter:

```dart theme={null}
enum _CardVariant { elevated, filled, outlined }   // private

StyledCard(…)            // default variant
StyledCard.outlined(…)    // named constructor sets _variant
StyledCard.filled(…)
```

Benefits: invalid parameter combinations are unrepresentable (each constructor only exposes what its variant supports — e.g. `elevation` exists only on the elevated `StyledCard`), and call sites read naturally. `StyledListTile` takes it further: variant-only, no default constructor.

## Token discipline

1. **Never hardcode colors or text styles** — everything comes from `context.colorTheme` / `context.textTheme`.
2. **Semantic over primitive** — `colors.surfaceBg`, not `SundialRef.sandLight[1]`. Direct primitive use is reserved for deliberate cases (wallpaper palettes, the solid-wallpaper dark-text rule).
3. **Accent for persona branding** — persona-responsive UI reads `colors.accent.*`; never a specific palette's colors.
4. **Test both brightness modes** — tokens make it work; you still verify contrast.

## Component reuse

Before building a custom widget:

```bash theme={null}
ls lib/design_system/components/   # design-system components
ls lib/widgets/common/             # app-specific reusable widgets
```

And check how existing call sites use a component: `grep -r "StyledTextField" lib/`.

## State management in components

Design-system components are `StatelessWidget` wherever possible. Only [`StyledTabBar`](https://design.slingshotai.com/components/styled-tab-bar) uses hooks (`HookWidget`) — and only to bridge a `TabController`. **No Riverpod inside `lib/design_system/`** — providers belong to app-level widgets.

## Accessibility

* Composite tappables get [`SemanticButton`](https://design.slingshotai.com/components/semantic-button) — one semantics node, `button: true`.
* Icons are decorative by default (`semanticLabel: null` on [`AshIcon`](https://design.slingshotai.com/components/ash-icon)); label at the button layer.
* Nav taps give haptic feedback (`HapticFeedback.selectionClick()` in `NavDestination`).

## Wallpaper legibility

Solid wallpaper → dark sand-12 ink (`contentOnBrand`), no scrim. Textured wallpaper → `ThemeOverride(brightness: dark)` + gradient scrim. Canonical implementation: [`StyledListTile`](https://design.slingshotai.com/components/styled-list-tile).

## Modern Flutter idioms

The codebase tracks recent Flutter/Dart features — patterns you'll see inside components:

* `Column(spacing: 8)` / `Row(spacing: 12)` instead of `SizedBox` separators
* `switch` expressions for variant dispatch
* Null-aware collection elements (`?child` inside children lists)
* Dot-shorthands for enum/static access (e.g. `mainAxisSize: .min`)
* `Color.withValues(alpha: …)` instead of deprecated `withOpacity`

Match these idioms when contributing — and check `pubspec.yaml`'s Flutter constraint before assuming an API's availability.


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