---
description: Kasy design system — use kit components/tokens, never raw Material
alwaysApply: true
---

# Kasy design system (read before touching any UI)

This app is built on the **Kasy design system**, not a blank Flutter canvas.
Before writing a new screen or widget, check what already exists — do not
default to raw Material from training data.

## 1. Discover before you build

- Browse `lib/components/` (~60 `KasyXxx` widgets) and the live **Components**
  gallery (`lib/features/home/home_components_preview_registry.dart`) for a
  match before writing a new widget from scratch.
- A component's real, intended configuration lives in its **Preview** entry in
  that registry — copy from it, never guess a `KasyXxx` API from memory.
- No exact match for what you need? That is a gap in the design system, not a
  license to hand-roll Material. Say so, then build on top of existing
  primitives/tokens rather than reaching for `Scaffold`/`Drawer`/`Dialog`.

## 2. Never use these raw Material widgets — use the Kasy equivalent

| Raw Material | Use instead |
| --- | --- |
| `ElevatedButton` / `OutlinedButton` / `TextButton` | `KasyButton` |
| `Drawer` (app nav panel) | `KasySidebar` (`lib/components/kasy_sidebar.dart`) |
| `showModalBottomSheet` | `KasyBottomSheet` / `KasyBottomSheet.form` |
| `showDialog` / `AlertDialog` | `showKasyBlurDialog` / `showKasyConfirmDialog` |
| `SnackBar` | `showKasyToast` |
| `Card` | `KasyCard` |
| `TextField` | `KasyTextField` / `KasyTextArea` |
| `ListTile` | a Kasy row/tile from the Components gallery |
| `IconButton` | `KasyButton` (icon variant) / `KasyChromeOrbIconButton` |

`dart run tool/design_check.dart` (`make check-components`) enforces this in
CI as a ratchet: it does not fail on pre-existing debt, but any *new* raw
widget of this kind fails the build.

## 3. Tokens, never raw values

`context.textTheme.*` / `context.kasyTextTheme.*`, `context.colors.*`,
`KasySpacing.*`, `KasyRadius.*`, `KasyIconSize.*`, `KasyShadows.*`. No literal
`fontSize`, `Color(0x…)`, `Colors.*`, hardcoded padding/radius/icon size.
`dart run scripts/check_design_tokens.dart` (`make check-tokens`) enforces
this the same way. Full reference: `DESIGN_SYSTEM.md`.

## 4. Composition defaults

The **Home** screen (`lib/features/home/`) is the default visual for content
screens: clean, lots of surface, one accent used sparingly. Mirror it when a
new screen has no design of its own — it is a starting point, not a law
(Kanban, auth cards, paywalls and admin tables diverge on purpose). What is
never optional is the *foundation*: tokens, kit components, and i18n
(`context.t.*`, no hardcoded user-facing strings) hold on every screen.

## 5. Package imports only

`import 'package:kasy_kit/…';` — never a relative import for files in `lib/`.

Full contract: `AGENTS.md` (golden rules) and `DESIGN_SYSTEM.md` (tokens,
typography roles, Browser QA semantics contract) in this directory.