Using with Claude Code

Claude Code reads CLAUDE.md automatically at the start of every session — this is the primary way Stratum’s architecture and rules are loaded into context. You can also supplement with llms.txt for full component API reference.

How context loading works

Automatic (always active): CLAUDE.md at the repo root is read by Claude Code on every session. It contains:

What Stratum is and how it’s structured
Hard rules (no hardcoded values, correct imports, atomic layer rules)
Current project status and next tasks
Key architectural decisions (ADRs)

On-demand (paste when needed): src/docs/llms.txt — comprehensive component API reference. Paste this when you want Claude to build features or components from scratch.

I'm building a new screen. Here's the full Stratum component API for reference:
[paste src/docs/llms.txt]

Now build me a notification preferences screen that...

Effective prompting patterns

Starting a feature session

I want to build a [feature name]. Let me describe what it needs:

- [user-facing behaviour]
- [which screen this lives on]
- [any state or API it connects to]

Use Stratum's atomic design layers. Start by identifying which template to use,
then which organisms fill the slots, then which molecules compose the organisms.

Building a new screen from scratch

Build a `UserProfileScreen` in src/screens/. It should:
1. Use `SettingsLayout` with title="Profile" and back navigation
2. Show a profile header Card with the user's avatar (Icon + Heading)
3. Have a `SettingsGroup` titled "Personal Info" with name, email, and phone as value rows
4. Have a `SettingsGroup` titled "Danger Zone" with a single "Delete Account" chevron row
5. Have a full-width destructive Button in the footer slot: "Delete Account"

Wire all the onPress handlers to console.log for now.
State should be local (useState). No API calls yet.

Extending an existing component

Read src/components/2-molecules/SettingsRow.tsx, then add an `isLoading` prop
that shows an ActivityIndicator instead of the rightAccessory when true.
Follow the same patterns as the existing isDisabled prop.
Add a snapshot test for the loading state.

Debugging a layout issue

Read src/screens/LoginScreen.tsx. The form is not centering vertically on tall
devices — it's sticking to the top. The template is AuthLayout. Diagnose the
issue and fix it without changing the AuthLayout API.

Session wrap-up (Claude Code handles this)

After completing work in Claude Code, the session should update:

project-docs/00-PROJECT-PLAN.md — check off completed tasks
project-docs/01-SESSION-LOG.md — add a session entry
CLAUDE.md — update Current Status and Next task

This is defined in CLAUDE.md’s “Session Wrap-up” section and Claude Code follows it automatically.

What Claude Code understands from CLAUDE.md

Because CLAUDE.md is always in context, Claude Code already knows:

The four hard rules (no hardcoded values, correct imports, no skipping layers, Surface over View)
The atomic design layer structure and when each layer is appropriate
The color philosophy (one accent + black + white + grays — no color proliferation)
The naming conventions (variant, size, tone, isDisabled, isLoading)
When to use SettingsGroup vs. stacking SettingsRow, etc.
The theme registry pattern (add one entry to register a new theme)
The createTheme() utility for extending an existing theme

You should not need to re-explain these rules in prompts — Claude Code already has them.

Adding llms.txt to Claude.ai (for strategic sessions)

When using Claude.ai (not Claude Code) for architecture decisions or planning:

Upload project-docs/00-PROJECT-PLAN.md + the relevant detail file
Paste src/docs/llms.txt into the conversation
Describe what you want to plan or decide

This is different from a Claude Code session — Claude.ai is for strategic decisions and planning, Claude Code is for implementation.

Common tasks Claude Code handles well

Component implementation

Read the existing Button atom in src/components/1-atoms/Button.tsx for reference.
Build a new `Divider` atom at src/components/1-atoms/Divider.tsx with:
- Props: orientation ('horizontal' | 'vertical'), color?, thickness?
- Default: horizontal, theme.colors.border, theme.border.thin
- Export DividerProps
- Add co-located tests in Divider.test.tsx (snapshot for each orientation × color)

Snapshot test regeneration

The SettingsRow component gained a new `isLoading` prop. Regenerate all
SettingsRow snapshots and any downstream snapshots (SettingsGroup) that reference it.

Theme audit

Read src/tokens/themes/slate.ts, obsidian.ts, and quartz.ts.
Check that every key in the AppTheme interface (from theme-protocol.ts) is
implemented in all six theme variants. Report any missing keys.

llms.txt consistency check

Read src/docs/llms.txt and compare the component APIs listed there against the
actual TypeScript interfaces in src/components/. Flag any props that are
documented incorrectly or missing.

Keyboard shortcuts in Claude Code

Esc — cancel the current generation
Ctrl+C — interrupt a running command
↑ — recall the last prompt (in terminal mode)

CLAUDE.md vs llms.txt — when to use each

Need	Source
Architecture rules, project context, ADRs	`CLAUDE.md` (auto-loaded)
Full component API reference (all props)	`src/docs/llms.txt` (paste on demand)
What’s been built and what’s next	`project-docs/00-PROJECT-PLAN.md`
Why a decision was made	`project-docs/04-DECISIONS.md`
What changed in the last session	`project-docs/01-SESSION-LOG.md`