Design System
Typography, colors, Kasy components, and how to customize without breaking the app.
The generated app already ships with a centralized design system. Change a token in one place, it changes across the whole app (web, iOS, Android).
Principle: clean, modern, minimalist. The Home screen is the visual reference.
Three places, three jobs
These are not three sources of truth. Each one has a job:
| Place | What it's for | When you touch it |
|---|---|---|
| Figma (Community file) | Rebrand and design. See the brand, edit variables, draft new screens. | Once for rebrand (and when inventing new UI). Then the AI moves the numbers into code. |
| Home → Design System / Components (in the app) | Preview what is already in code: tokens, variants, states. Live mirror. | You don't edit tokens here. You check light/dark after a rebrand. |
DESIGN_SYSTEM.md (project root) | Contract for AI and humans: use tokens, use KasyButton, nested cards = filled, etc. | Rarely. Update when kit behavior changes, not on every color tweak. |
The runtime source of truth is only the code: lib/core/theme/ + lib/components/.
Why keep the .md instead of asking the AI to “follow the Design System screen”? That screen runs inside Flutter. The editor AI reads repo files. Without a written contract it invents raw Material and hardcoded sizes (we already saw that with Card). Keep the .md as a ruler, not a duplicate of every token table.
Typical rebrand flow: Figma (variables) → AI syncs colors.dart / theme → verify on the in-app Design System screen. Details in Figma (rebrand and screens).
Layers
| Layer | Where | Example |
|---|---|---|
| Typography | KasyTextTheme | context.textTheme.pageTitle |
| Icons | KasyIconSize | KasyIconSize.rowLeading |
| Spacing | KasySpacing | KasySpacing.md (16) |
| Radii | KasyRadius | KasyRadius.lg (16) |
| Colors | context.colors.* | Resolves light/dark on its own |
| Components | lib/components/ | KasyButton, KasyCard, KasyTextField |
Via MCP: before creating or editing any screen, the assistant should call list_components — it scans lib/components/ live (not a fixed list) and returns every KasyXxx with a usage summary, so it never invents raw Material when a Kasy component already covers it. See Kasy MCP.
KasyScreen
Wrap new screens in KasyScreen to inherit the background, gutter, max width (~600), and an optional card:
KasyScreen(
title: 'My screen',
child: ...,
)You're not locked in
Rebranding = swapping tokens (primary color, typography) in one place. Components accept variants and overrides.
Optional guard-rail
dart run tool/design_check.dartWarns you when a screen uses a raw value (a Material color/font directly) instead of the design system. Optional, doesn't block the build.
Last updated on 08/02/2026