Skip to content
All posts

How to build cross-platform templates AI coding tools actually respect

DaveOTF Kit
7 min read
How to build cross-platform templates AI coding tools actually respect

Watch any AI coding tool — Claude Code, Cursor, Antigravity, Lovable, Aider, Continue — work inside an unfamiliar codebase for ten minutes, and you'll see the same three failure modes:

  1. It invents conventions that don't exist ("here's a new utility I made up because I couldn't find an existing one").
  2. It ignores conventions that do exist ("I see you use TanStack Query everywhere, but I'll use a fresh useEffect for this fetch because the prompt didn't say not to").
  3. It mistakes scaffold for product ("I see you import from @/components/ui/button — so I'll create a new component at @/components/MyButton.tsx").

Each failure has the same root cause: the codebase isn't legible enough to a model that hasn't seen it before. The fix isn't to switch models; it's to write code AI models can read.

Below are the conventions we've landed on while building the OTF SDK and the kits that ship on top of it. They're not opinions — every one came from watching an AI tool fail and asking "what would have made this clearer?"

1. One file, one component, one idea

The biggest thing we changed: every component sits in its own file with no clever inheritance, no index.ts re-exports inside a component folder, no shared base classes. A model that opens Button.tsx should see the entire button.

// packages/ui/src/primitives/button.tsx — entire file is ~80 lines
export const buttonVariants = cva(...)
export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(...)
export type ButtonProps = ...

Compare to a file that re-exports from three other files: an AI looking at the import from '@otfdashkit/ui' has to follow chains to know what Button actually is. With our flat layout, the answer is a single file read.

2. Naming carries meaning

Names are the cheapest documentation. We invest hard in them:

  • useCreateProject — "this is a TanStack Query mutation hook for creating a project"
  • useProjects — "this is a TanStack Query query hook for the list"
  • <Stat> — "single-purpose stat tile, not a generic card"
  • <Persona> — "avatar + name + role row, not a generic user list item"

When an AI sees useCreateProject, it doesn't have to read the file to know it returns a useMutation result. It can call mutate / mutateAsync confidently because that's what the name implies.

One codebase. iOS, Android, and web.

The Fitness Kit is a mobile starter with its own API, with sign-in and a database. Live demo at fitness-preview.otf-kit.dev.

See the live demo

3. Patterns live in the file system, not in your head

Every recurring pattern in the kit gets one canonical implementation that reads like a template:

  • Hook shape → src/hooks/useProjects.ts (the optimistic-update template)
  • Hono route shape → server/routes/projects.ts (CRUD template)
  • New screen shape → step-by-step in CLAUDE.md ("create file at src/pages/..., wrap in <FadeIn>, add to router")

When a user asks Claude "add a tasks endpoint", Claude reads CLAUDE.md, finds the route shape, copies projects.ts, and adapts. No invention.

4. The AI config file is non-optional

Each OTF kit ships a root AGENTS.md, CLAUDE.md, and .cursorrules, plus 22–27 task prompts in ai/prompts/ (checked 13 October 2026). They're maintained with the codebase and share a structure:

  1. Stack table — what tools and at what versions
  2. File map — top-down where things live
  3. Patterns — 5-10 lines of code per recurring shape
  4. Conventions — strict TypeScript, Tailwind tokens only, no comments unless // Why: ...
  5. Deploy — exact command

Without this, opening the kit in Claude Code and asking "add a new screen" produces something that almost-works but uses a different naming convention than the rest of the codebase. For a related example, see how landing templates ship agent docs with the code.

OpenCode reads AGENTS.md as project instructions. The OpenCode setup guide explains how the SaaS Dashboard kit's files guide an edit. The guide records this dated check: "On 13 October 2026, the kit's own type-check passes in a fresh install. Our test change added no type errors." This is a narrow type-check result; it does not claim every generated change builds or that the whole app was tested. For a separate example of how agent capabilities affect what templates need to ship, see what Cursor's parallel agents change for templates.

A developer reviews CLAUDE.md, .cursorrules, and AGENTS.md project guidance before editing a codebase.

5. Tokens, not hex

We never put a hex color outside the tokens package. Every component reads --background, --primary, --card, etc. — variables defined by @otfdashkit/tokens.

This sounds like a cosmetic choice. It isn't. When an AI asks "make this button red" and the codebase has hex everywhere, the AI guesses a hex. When the codebase has only tokens, the AI either asks ("which red — destructive?") or reads the token file and picks hsl(var(--destructive)). Either is better than a hardcoded color drifting into the codebase.

We enforce this with @otfdashkit/eslint-plugin-otf-design — it lints out hex literals and inline style={{ background: '...' }} outside the tokens package.

6. Strict types are AI ergonomics, not just code quality

We turned on strict and noUncheckedIndexedAccess. Every prop is typed. Every hook return is typed. No any, no as casts unless commented.

The reason: when an AI tool generates a call like useProjects().data.find(p => p.title), TypeScript catches the missing null check at edit time. The AI sees the error and adapts. Without strict mode, the bug ships.

7. Comments only for why, never for what

Almost every comment in the OTF kits starts with // Why: or doesn't exist. We don't have "// fetch the user" above const { data } = useUser() — that comment is just noise. A model reading the file already knows it fetches the user.

But this:

// Why: Tamagui's defaultConfig pins every weight slot to 300 (thin), which makes
// <H1> headings render drastically lighter than `Text fontWeight=700` elsewhere —
// visually inconsistent. We override only the weight ramp via createFont.
const headingFont = createFont({ ... })

— this is gold for an AI tool. It encodes a design decision that's not derivable from the code alone. If someone later asks Claude "should we drop this createFont override?", Claude reads the comment and pushes back: "no, removing this would regress the heading rendering".

8. The deployment files are in the repo

SaaS Dashboard and Fitness ship scripts/deploy-worker.sh (Cloudflare Workers), a Dockerfile for any container host and a deployment guide (docs/DEPLOYMENT.md). When Claude is asked to deploy, it reads the guide and follows the documented steps instead of constructing its own invocation that might miss an env var or a health check. Convention beats configuration.

9. lessons.md saves you from rediscovering the same fix

Every time we hit a non-trivial bug — Metro can't resolve a workspace package, dual-React crashes inside a webpack bundle, Tamagui's peerDeps don't auto-install — we append a lesson to docs/lessons.md:

## Symptom: `Unable to resolve "@otfdashkit/ui-native"` from a kit

**Cause**: Metro doesn't follow workspace symlinks across the monorepo by default
**Fix**: `npm install --install-links` in the kit's directory before `bun dev`
**Reference**: lessons.md ~line 375

Our master AGENTS.md has a hard rule: before reaching for a custom resolver / Metro config / plugin, grep docs/lessons.md for the symptom. If it's there, use the documented fix. Don't rebuild from scratch.

This rule applies to AI agents too. When Claude hits "Unable to resolve" for the third time in three months, it grep's lessons.md, finds the fix, applies it, and doesn't rebuild a metro.config.js from scratch.

What this gets you

A neutral projects list gives an agent a concrete screen pattern to extend. The following is illustrative; use the fields and components already present in your own project.

function ProjectsList({ projects }: { projects: Project[] }) {
  return (
    <ul>
      {projects.map((project) => (
        <li key={project.id}>
          <span>{project.name}</span>
          <span>{project.status}</span>
        </li>
      ))}
    </ul>
  )
}

For example, if you ask an agent to add a status filter to a projects screen, it can:

  1. Read the repository's instructions.
  2. Find the existing projects query and page.
  3. Reuse the current list and styling patterns.
  4. Add the filter in the established location.
  5. Run the documented type-check and report its result.

This is a workflow to try, not a guarantee that an AI-generated change will be correct. Review the diff, run the checks that matter for your project, and test the user-facing behavior before shipping.

If you want to see the conventions in a working codebase, explore the SaaS Dashboard kit or the Fitness & Wellness kit. You can also start here to choose a next step.

Sources

ai-toolscross-platformtemplates
OTF Fitness Kit

Stop wiring. Start shipping.

  • Sign-in and a database wired in, with its own API
  • iOS + Android + web from one codebase
  • AI configs pre-tuned + 20+ task prompts per kit included
Free starter

Ship your first screen tonight — free starter in your inbox

The quickstart, the SDK repo and the live kit demos, on this screen and in your inbox.

No spam. Unsubscribe any time.

Free with your email

Get the free AI configs pack

The AI files every kit ships with. Drop them in and your AI tool knows your project.

  • CLAUDE.mdProject context
  • .cursorrulesRules for Cursor
  • prompts/Task prompts

No spam. Unsubscribe any time.