Skip to main content
Sundial’s source of truth is the code in 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).
4

Document it

Add the token to the Semantic Colors (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 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).
  • 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 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.