create-widget

Creating New Widgets

Step-by-step guide to creating widgets that follow the design system's architecture and conventions.

File Naming Conventions

Widget Files

Pattern: {widget_name}_widget.dart

// ✅ Good
scaffold_widget.dart
button_widget.dart
cupertino_text_field_widget.dart

// ❌ Avoid
scaffold.dart
btn_widget.dart
textfield.dart

Class Naming

Pattern: {Name}Widget

class ScaffoldWidget extends StatelessWidget {}
class ButtonWidget extends StatelessWidget {}
class IconWidget extends StatelessWidget {}

Widget Template

Basic StatelessWidget

// lib/src/widgets/my_custom_widget.dart
import 'package:flutter/cupertino.dart';
import '../../ios_design_system.dart';

/// iOS-style custom widget for [purpose].
///
/// This widget provides [main features] with automatic theme adaptation
/// for both light and dark modes.
///
/// ## Example
///
/// ```dart
/// MyCustomWidget(
///   title: 'Example',
///   subtitle: 'Description',
///   onPressed: () {},
/// )
/// ```
///
/// See also:
///
///  * [RelatedWidget], which provides similar functionality.
class MyCustomWidget extends StatelessWidget {
  /// Creates a custom widget.
  ///
  /// The [title] parameter is required and must not be null.
  const MyCustomWidget({
    required this.title,
    this.subtitle,
    this.onPressed,
    super.key,
  });

  /// The primary title text.
  final String title;

  /// Optional subtitle text shown below the title.
  final String? subtitle;

  /// Called when the widget is tapped.
  ///
  /// If null, the widget will be non-interactive.
  final VoidCallback? onPressed;

  @override
  Widget build(BuildContext context) {
    final theme = IosTheme.of(context);

    return CupertinoButtonWidget(
      onPressed: onPressed,
      color: switch (theme) {
        IosLightThemeData() => theme.defaultSystemBackgroundsColors.primaryLight,
        IosDarkThemeData() => theme.defaultSystemBackgroundsColors.primaryDarkElevated,
      },
      borderRadius: BorderRadius.circular(12),
      padding: const EdgeInsets.all(16),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            title,
            style: theme.typography.bodyBold.copyWith(
              color: theme.defaultLabelColors.primary,
            ),
          ),
          if (subtitle != null) ...[
            const SizedBox(height: 4),
            Text(
              subtitle!,
              style: theme.typography.caption1Regular.copyWith(
                color: theme.defaultLabelColors.secondary,
              ),
            ),
          ],
        ],
      ),
    );
  }
}