# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Den Design System (DDS)** — A Flutter UI component library providing 45+ pre-built, highly customizable widgets. The app itself is a Storybook-based showcase for interactive component demos.

- **Package name:** `den_design_system`
- **SDK:** Dart ^3.5.3, Flutter
- **Storybook:** `storybook_flutter` for component documentation and demos

## Commands

```bash
flutter pub get          # Install dependencies
flutter run              # Run the Storybook demo app
flutter analyze          # Static analysis (uses flutter_lints)
flutter test             # Run tests (minimal coverage currently)
```

## Architecture

### Directory Layout

- `lib/widgets/{component}/` — Core UI components (e.g., `button/`, `checkbox/`, `dropdown/`)
- `lib/stories/` — Storybook story files for each component (`{component}_story.dart`)
- `lib/layouts/` — Full-page layout examples (sign-in, sign-up, profile, etc.)
- `lib/utils/{component}/` — Enums and helpers per component (`{component}.utils.dart`)
- `lib/themes/app_theme.dart` — Light/dark ThemeData definitions
- `lib/colors/app_color.dart` — `ThemeColors` color constants (primary: `#F15A29` orange)
- `lib/main.dart` — Storybook entry point, imports all stories

### Component Pattern

Every component follows this structure:
1. **Widget class** prefixed with `DDS` (e.g., `DDSButton`, `DDSCheckbox`, `DDSTextField`)
2. **Enums** for variants/sizes/shapes in `lib/utils/{component}/`
3. **Highly parameterized constructors** — components have extensive color/style customization params
4. **Local state only** — `StatefulWidget` + `setState()`, no global state management library
5. **Story file** in `lib/stories/` with Storybook knobs for interactive testing

### Naming Conventions

- Widget classes: `DDS{ComponentName}` (PascalCase)
- Story files: `{component}_story.dart` or `{componentName}_story.dart` (mixed case exists)
- Layout files: `{screen}_layout.dart`
- Utils: `{component}.utils.dart`
- File naming is not strictly enforced (`file_names` lint rule is ignored)

## Linting Rules

Key analyzer config (`analysis_options.yaml`):
- `prefer_relative_imports: error` — **Must use relative imports**
- `prefer_const_constructors: ignore` — Const not enforced
- `avoid_print: ignore` — Print statements allowed
- `non_constant_identifier_names: ignore` — Flexible naming
- `file_names: ignore` — Mixed file naming conventions accepted
- Required: `always_declare_return_types`, `avoid_empty_else`

## Key Dependencies

- `storybook_flutter` — Component showcase framework
- `dio` — HTTP client
- `flutter_svg` — SVG rendering
- `image_picker`, `camera`, `image_editor_plus` — Image capture/editing
- `file_picker` — File selection
- `intl_phone_field` — Phone number inputs
- `flutter_tabler_icons` — Icon set
- `cached_network_image` — Network image caching
- `flutter_card_swiper`, `swiping_card_deck` — Card swiping interactions
- `custom_refresh_indicator` — Pull-to-refresh

## Branching

- **Main branch:** `master`
- **Version format:** `YYMM.patch.build` (e.g., `2512.0.2`)
