Quickstart

1. Import the barrel file

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

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:

@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:

ls lib/design_system/components/   # design system components
ls lib/widgets/common/             # app-specific reusable widgets

TextField(
  maxLength: 250,
  decoration: InputDecoration(/* custom styling… */),
  // …custom counter logic…
)

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 section for every widget.

4. Accent-colored (persona) UI

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

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

The golden rules

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.

Semantic over primitive

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

Use accent tokens for persona branding

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

Test both brightness modes

Every screen must hold up in light and dark. If you need to force a subtree, use ThemeOverride.

Getting Started

Craft and Foundations

Brand

Design System

For Agents

1. Import the barrel file

2. Read tokens from context

3. Reach for existing components first

4. Accent-colored (persona) UI

The golden rules