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

# Contributing

> How to extend Sundial — tokens, icons, components — and keep these docs true

Sundial's source of truth is the code in [`lib/design_system/`](https://github.com/slingshot-ai/ash-mobile-app/tree/main/lib/design_system). Changes land there; these docs mirror it.

## Adding a color token

**1. Decide the layer**

New primitive shade? → `reference_colors.dart`. New purpose? → a semantic token in `semantic_colors.dart` referencing existing primitives. Persona-dependent? → a field on `AccentColors`.

**2. Update all the places**

For `DesignSystemColors`: the field, the constructor, `.light`, `.dark`, `copyWith`, **and `lerp`**. A token missing from `lerp` snaps instead of animating on theme changes.

**3. Wire Material if relevant**

If stock Material widgets should use it, add it to the component themes in `app_theme.dart` (see [Material bridge](https://design.slingshotai.com/theming/material-bridge.md)).

**4. Document it**

Add the token to the [Semantic Colors](https://design.slingshotai.com/foundations/colors/semantic.md) (or relevant) page with its light/dark mapping.

## Adding a typography token

Same drill in `typography.dart`: field + constructor + `base` + `copyWith` + `lerp` (colors come from `light`/`dark` via the blanket `copyWith`). Stick to the 5-category × 3-size grid — a new size within a category beats a new one-off style.

## Adding an icon

1. Drop the SVG in `assets/icons/` (subfolders like `activities/`, `personas/` are fine).
2. Register it in the `AshIcons` enum in `ash_icon.dart` — the enum value's string is the path fragment: `myIcon('MyIcon')` → `assets/icons/MyIcon.svg`.
3. Prefer [Material Symbols](https://design.slingshotai.com/foundations/iconography.md#symbols-material-symbols-rounded) for generic glyphs — `AshIcons` is for artwork that's ours.

## Adding a component

* **Location**: foundational UI → `lib/design_system/components/` + export from `design_system.dart`; feature-specific reusable → `lib/widgets/common/`.
* **Naming**: `Styled*` for Material wrappers, `Ash*` for brand primitives.
* **Variants**: private enum + named constructors ([the pattern](https://design.slingshotai.com/patterns/conventions.md#the-variant-pattern)).
* **Tokens only**: all colors/text via `context.colorTheme` / `context.textTheme`.
* **Stateless** unless it genuinely needs local state; no Riverpod in the design system.
* **Accessibility**: composite tappables wrapped in `SemanticButton`; decorative icons unlabeled.
* **Doc comments**: every public class and non-obvious parameter — doc comments are where these pages come from.
* **Docs**: add a component page here following the shared template (purpose → variants → API table → tokens → example → source link).

## Versioning & changelog

Sundial is versioned as a system — the navbar version on this site tracks the design system as it ships in the app, not the docs. When you change the system:

1. **Add an `<Update>` entry** to the [Changelog](https://design.slingshotai.com/changelog.md) describing the change, dated, with the PR link.
2. **Bump the version** when the change warrants it:
   * **Major** — breaking renames or removals of tokens/components, palette restructuring
   * **Minor** — new tokens, new components, new component variants
   * **Patch** — value tweaks (a hex adjustment, a radius change), bug fixes
3. **Update the navbar badge** — the `v…` link in `docs.json`'s `navbar.links` is set by hand; keep it matching the newest changelog entry.

Not every commit needs an entry — cosmetic refactors with no visible change can skip the changelog. Every *visible* change to tokens, components, or theming gets one.

## Keeping these docs accurate

This site is hand-maintained against the Dart source. When you change tokens or component APIs, update the corresponding page in the same working session. Rule of thumb: **every hex value, metric, and parameter on this site must be traceable to a line of code** — if you can't point to the line, don't write it.


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