clarity AGENTS.md

Expo HAS CHANGED

Read the exact versioned docs at https://docs.expo.dev/versions/v57.0.0/ before writing any code.

The design system

Every visual value comes from one place: constants/theme.ts. Read it before styling anything.

import { colors, radius, spacing, springs, type } from '@/constants/theme';
import { useTheme } from '@/hooks/use-theme';
import { GlassSurface, PrimaryButton, SectionHeader, ThemedText } from '@/components/ui';

Four rules, in the order they get broken:

1. No hardcoded visual values. No hex colors, no fontSize, no raw spacing or radius numbers outside constants/. A value used twice is a token. A genuine one-off (an optical nudge on a glyph) may stay inline with a comment saying why — that is the only exemption, and the audit below counts the rest.
2. Colors resolve through useTheme(), never useColorScheme() plus a local light/dark map. That pattern is what gave the app two greens, six card radii, and seven grays.
3. Text is <ThemedText variant=… tone=… />. Pick a ramp step and an ink tone; weight overrides the step's face. Nothing else names a fontSize.
4. Frosted cards are <GlassSurface>, not a hand-rolled isLiquidGlassAvailable() branch. Exception: a card whose child needs its own glass must render <GlassSurface style={StyleSheet.absoluteFill} /> as an absolute sibling, because nested glass does not render on iOS 26.

Components import tokens; screens import components. A screen using spacing to lay out its own children is fine. A screen defining a button color is drift.

Extracting a component

Promote a view into components/ui/ only when all three hold: it appears in two or more screens, it has a nameable role, and its API is smaller than its implementation. Until then it stays where it is. Never wrap a platform component that already carries the design language (Switch, stack headers, @expo/ui views) just to route it through the system.

Auditing for drift

The whole point is that these stay near zero. Run from the repo root: