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

# Color & Depth

> Design rationale: building palettes, purposeful shadows, borders as a last resort, and finished edges

## Color

When building or extending a palette:

* **You need more colors than you think.** A real UI needs 8–10 shades of grey, 5–9 shades of the primary, and multiple shades per semantic color. (Sundial's answer: 11-shade ramps for every family — see [Reference Colors](https://design.slingshotai.com/foundations/colors/reference.md).)
* **Use HSL** — it maps to human perception far better than hex or RGB.
* **Don't just lighten and darken — rotate the hue.** Lighter shades shift toward the nearest bright hue (60°, 180°, 300°), darker shades toward the nearest dark hue (0°, 120°, 240°). This produces richer, more natural ramps.
* **Define the edges first:** pick the darkest and lightest shades, then fill the gaps. The middle shade should work as a button background.
* **Never rely on color alone to communicate meaning.** Supplement with icons, weight, or position — critical for accessibility.
* **No grey text on colored backgrounds** — it looks washed out. Use a lighter or darker shade of the background's own hue. (This is the `onButton` = accent-200 rule — see [Accent Colors](https://design.slingshotai.com/foundations/colors/accent.md).)

## Depth & shadows

Shadows serve a purpose or don't exist:

* **One light source, from above.** Every shadow in the UI agrees on where light comes from.
* **A small elevation system** (3–5 levels), subtle to pronounced: tight shadows for low elevation (buttons), larger diffused ones for high elevation (modals, dropdowns).
* **Combine two shadows** for realism: a tight dark one at the contact edge plus a soft ambient one.
* **Shadows communicate interactivity** — raised feels clickable, flat feels static. Use that intentionally.
* In flat contexts, create depth **through color**: lighter surfaces read as closer. This is Sundial's primary mechanism — the `surfaceBg → surfaceElevated → surfaceHigh` ladder — with real shadows reserved for genuinely floating things (the nav bar, the elevated card).

## Borders & separation

Borders are a **last resort** for separating content. In order, try:

1. More spacing
2. A different background color
3. A subtle shadow
4. …and only then a border — light and low-contrast, so it separates without shouting

Too many borders make an interface feel busy; every border competes for attention.

## Images & user content

* User-uploaded content (avatars, photos) lives in **fixed-size containers** with cover-fit cropping. Never let user content dictate layout dimensions.
* Text over images needs **guaranteed** legibility: overlays, lowered image contrast, or text scrims — don't hope the image is dark enough. (Sundial's wallpaper scrim rules encode this — see [Wallpapers](https://design.slingshotai.com/foundations/wallpapers.md#legibility-rule).)
* Icons and images have an intended display size — don't scale a 16px icon to 64px. Use the right asset, or enclose a small icon in a larger shape.
* Prevent background bleed on light-edged images with a subtle inset shadow rather than a border.

## Empty states & finishing touches

* **Empty states are design opportunities, not afterthoughts.** A blank screen with “No data yet” is a missed chance to guide, reassure, or delight.
* **Replace defaults with intentional choices:** custom bullet icons, styled checkboxes, accent borders on cards and alerts. Small upgrades to defaults signal craft.
* Accent borders or colored top-edges add personality without complexity.
* Break up monotonous layouts by alternating section background colors.


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