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

# Quickstart

> Use Sundial tokens and components in a widget in five minutes

## 1. Import the barrel file

Everything — tokens, theme, components, context extensions — is exported from one file:

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

## 2. Read tokens from context

Inside any `build` method, grab the current theme's tokens via the two `BuildContext` extensions:

```dart theme={null}
@override
Widget build(BuildContext context) {
  final colors = context.colorTheme;      // DesignSystemColors
  final typography = context.textTheme;   // DesignSystemTypography

  return Container(
    color: colors.surfaceElevated,
    child: Text(
      'Hello from Sundial',
      style: typography.bodyLarge.copyWith(color: colors.contrastBold),
    ),
  );
}
```

These resolve against the ambient `Theme`, so the same code renders correctly in light mode, dark mode, and under any persona accent palette.

## 3. Reach for existing components first

Before building a custom widget, check what already exists:

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

```dart Don't — reinvent with raw Material theme={null}
TextField(
  maxLength: 250,
  decoration: InputDecoration(/* custom styling… */),
  // …custom counter logic…
)
```

```dart Do — use the Styled wrapper theme={null}
StyledTextField(
  controller: controller,
  hintText: 'Enter text',
  maxLength: 250,              // default is 250
  showCounterAfterChars: 200,  // counter appears after this threshold
)
```

Variants use **named constructors**, not parameters: `StyledCard.outlined()`, `StyledCard.filled()`, `StyledTextField.underline()`. See the [Components](https://design.slingshotai.com/components/styled-card.md) section for every widget.

## 4. Accent-colored (persona) UI

Persona-branded elements use the accent tokens nested in the color theme:

```dart theme={null}
ElevatedButton(
  style: ElevatedButton.styleFrom(
    backgroundColor: colors.accent.button,
    foregroundColor: colors.accent.onButton,
  ),
  onPressed: () {},
  child: Text('Primary Action'),
)
```

(In practice, a plain `ElevatedButton` already gets these colors from the app theme — see [Material bridge](https://design.slingshotai.com/theming/material-bridge.md).)

## The golden rules

**1. Never hardcode colors or text styles**

Every color comes from `context.colorTheme`, every text style from `context.textTheme`. No `Color(0xFF…)`, no `TextStyle(fontSize: …)` in feature code.

**2. Semantic over primitive**

Use `colors.surfaceBg`, not `SundialRef.sandLight[1]`. Semantic tokens adapt to light/dark automatically; primitives don't.

**3. Use accent tokens for persona branding**

Anything that should follow the user's persona uses `colors.accent.*` — never a specific palette's colors.

**4. Test both brightness modes**

Every screen must hold up in light and dark. If you need to force a subtree, use [ThemeOverride](https://design.slingshotai.com/components/theme-override.md).


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