FlutterInit

DESIGN.md Explained: Giving Your AI Agent the Architecture Decisions It Needs

Guideai context#design-md#ai-context#theme#flutter#flutterinit

DESIGN.md is FlutterInit’s design-system brief for agents: theme, colors, typography, spacing, and motion — so UI changes stay on-token.

Arjun Mahar
Arjun Mahar@arjun_mahar1
2 min read

DESIGN.md is not a moodboard. It’s a generated contract for UI work: which theme preset you chose, how colors and type resolve, and which spacing/motion tokens exist. Agents that read it stop inventing random EdgeInsets.all(13) and hex colors.

What gets written

At generation time FlutterInit renders DESIGN.md from your theme config. Typical sections:

  • Theme overview — preset, Material 3 vs Cupertino notes, dark mode
  • Color system — context.colors / context.appColors, no hardcoded hex
  • Typography — textTheme roles; custom font families when uploaded
  • Spacing, borders, motion — AppSpacing, AppBorders, AppShadows, AppDurations, AppCurves
  • Pointers back to AGENTS.md for structural rules

Those tokens live under lib/src/theme/ (for example theme_constants.dart, color_schemes.dart, theme.dart).

Why agents need this

Without DESIGN.md, an agent “improving” a login screen will:

  • Inline Color(0xFF…)
  • Mix font sizes that ignore textTheme
  • Ignore dark mode semantic colors

With DESIGN.md, you can say: “Restyle the auth screens using DESIGN.md tokens only.” That’s a constrained, reviewable change.

How it pairs with AGENTS.md

FileAnswers
AGENTS.md / CLAUDE.mdWhere code goes, which state/nav/backend patterns
DESIGN.mdHow UI should look and feel
SETUP.mdHow to run and configure backends

Architecture without design tokens still produces ugly inconsistencies. Design tokens without architecture still dump logic in widgets. You want both.

Practical workflow

  1. Change brand colors in the FlutterInit wizard (or edit theme files carefully).
  2. Keep DESIGN.md in sync when you change generation inputs (regenerate or update the doc).
  3. In Cursor, reference DESIGN.md on any visual task.
  4. Reject PRs that introduce raw hex or one-off ThemeData in features.

Deeper agent workflow: How to Get More Out of Cursor. Broader moat: Why We Generate CLAUDE.md and AGENTS.md.

Generate a themed project on /create and open DESIGN.md before you touch UI.

Ready to build?

Generate this project in seconds

FlutterInit scaffolds the entire structure described in this guide — wired up, typed, and ready for flutter run.

Start Generating →

Related guides