Using with Cursor

Cursor’s AI understands codebases through context — the more precise context you give it, the more idiomatic the generated code. This guide shows you how to get Stratum-correct code from Cursor’s AI on the first try.

Step 1: Add llms.txt to your context

The fastest way to prime Cursor for a Stratum session is to paste src/docs/llms.txt directly into the chat.

// In Cursor chat:
I'm working in a React Native (Expo) project that uses Stratum, an atomic design system.
Here's the system context:

[paste contents of src/docs/llms.txt]

Alternatively, reference it via @file:

@src/docs/llms.txt
Build me a settings screen with four sections: Profile, Notifications, Privacy, and Account.

Step 2: Use the right prompt patterns

Stratum’s atomic structure means Cursor needs to know which layer to target. Vague prompts produce generic RN code; layer-specific prompts produce Stratum code.

Instead of:

“Build a settings page”

Use:

“Build a SettingsScreen using SettingsLayout + four SettingsGroup organisms. The Notifications group should have two switch rows wired to local state.”

Instead of:

“Add a form”

Use:

“Add a login form using AuthLayout + AuthForm in login mode. Wire email/password to useState. Validate on submit — empty email shows ‘Enter a valid email’, password under 8 chars shows ‘Password too short’. Pass errors as emailError/passwordError props.”

Instead of:

“Show a badge”

Use:

“Use a Badge with variant="success" and label="Active" next to the user’s name in this Card.”

Step 3: Reference the HIG for visual decisions

The Stratum HIG app (app/) is your source of truth for what components look like and when to use them. When Cursor suggests a pattern you’re not sure about, cross-check it in the HIG.

/atoms — individual component playgrounds with variant/size/state toggles
/molecules — composed UI units with do/don’t examples
/organisms — section-level composites
/patterns — cross-layer composition examples

Common Cursor prompts

Build a component page

@src/docs/llms.txt

Build a React Native screen called `ProfileScreen` that uses:
- `SettingsLayout` with title="Profile" and an onBack prop
- A `Card` with padding="lg" showing the user's avatar area (use `Icon` with icon={User} from phosphor-react-native, size="xl", color="accent") and their name as `Heading level={2}`
- A `SettingsGroup` titled "Contact" with two value rows: Email and Phone
- A `Button` with variant="destructive" at the bottom for "Delete Account"

Follow Stratum's rules: no hardcoded colors or sizes, use theme tokens only.

Add a feature to an existing screen

@src/screens/SettingsScreen.tsx
@src/docs/llms.txt

Add a new `SettingsGroup` titled "Appearance" to the SettingsScreen with:
- A "Theme" row using rightAccessory="value", showing the current theme name, that opens a theme picker on press
- A "Dark mode" row using rightAccessory="switch" wired to a toggleColorScheme call from useThemeToggle

Create a custom theme

@src/docs/llms.txt
@src/tokens/themes/slate.ts

Create a custom theme called "ocean" that extends slateThemeLight. Change:
- accent → '#0EA5E9' (sky blue)
- accentHover → '#0284C7'
- accentSubtle → '#F0F9FF'

Create both light and dark variants, then show me how to register it.

What Cursor gets right automatically (when primed)

With llms.txt in context, Cursor will:

Import from @/components and @/tokens correctly
Use useTheme() instead of hardcoded colors
Choose FormField over bare Input for form fields
Use SettingsGroup instead of manually stacking SettingsRow components
Respect accessibilityLabel requirements on IconButton
Avoid the palette (colors.ts) and reach for semantic theme.colors.* slots instead

What to watch out for

Cursor may reach for bare <View> instead of <Surface>. Surface handles BlurView for the Quartz theme automatically. If you see <View style={{ backgroundColor: theme.colors.surface }}>, prompt: “Use <Surface> instead of a bare View here.”

Cursor may validate inside organisms. AuthForm, for example, should never validate — it’s a controlled component. Validation belongs in the Screen. If Cursor adds validation logic inside AuthForm, prompt: “AuthForm is controlled — move the validation logic to the Screen and pass errors back as emailError/passwordError props.”

Cursor may hardcode pixel values. If you see paddingHorizontal: 16 instead of padding: spacing.md, prompt: “Replace all hardcoded values with Stratum tokens from @/tokens.”

Cursor Rules file

Add this to .cursor/rules/stratum.md in your project to have Cursor apply Stratum conventions automatically:

This project uses Stratum (an atomic design system for React Native/Expo).

## Always
- Import components from `@/components`
- Import tokens from `@/tokens`
- Access theme via `const theme = useTheme()` from `@/hooks/useTheme`
- Use `<Surface>` instead of bare `<View>` for themed containers
- Use `FormField` instead of bare `Input` in forms (it handles label + error)
- Use `SettingsGroup` instead of stacking individual `SettingsRow` components
- Use `ListSection` instead of stacking individual `ListItem` components
- Use `theme.colors.*` semantic slots, never hardcoded hex colors
- Use `spacing.*` tokens, never hardcoded pixel values

## Never
- Hardcode colors, sizes, or font values
- Import from `src/tokens/colors.ts` (palette) in components — use theme.colors.* only
- Add validation logic inside organisms — that belongs in Screens
- Skip atomic layers (put atoms directly in Templates without an organism in between)
- Use more than one primary Button per screen
- Use the destructive variant for reversible actions (logout is reversible — use ghost)

## Atomic layer decision guide
- Single text label → Text or Heading atom
- Single interactive button → Button or IconButton atom
- Form input with label + error → FormField molecule (not bare Input)
- Settings preference row → SettingsRow (multiple rows → SettingsGroup)
- Content list row → ListItem (multiple rows → ListSection)
- Full-screen auth → AuthLayout + AuthForm
- Full-screen settings/detail → SettingsLayout