create-ui-widget

UI Widget Creation Skill

This skill defines the process for adding new reusable UI widgets to the packages/app_ui/ package.

[!NOTE] For details on mapping Figma designs, typography, HSL colors, spacing, and asset generation, refer to the Design-to-Code Skill.

1. Directory Structure

Widgets must be placed in packages/app_ui/lib/src/widgets/ by category:

packages/app_ui/lib/src/widgets/
├── buttons/
│   └── primary_button.dart    # Class name: YzPrimaryButton
├── layout/
│   └── web/
│       └── scaffold_web.dart  # Class name: YzScaffoldWeb

2. Implementation Rules

Follow these rules when implementing a widget in app_ui:

• Naming: Class names must prefix with Yz (e.g. YzPrimaryButton). File names must be snake_case without yz_ prefix (e.g. primary_button.dart).
• Generic Naming: Always use generic, domain-agnostic names for widgets. For example, name a button YzPrimaryButton rather than YzLoginButton, even if it is currently only used on a specific screen.
• Web suffix: If a web variant exists for a shared concept, append Web (e.g., YzScaffoldWeb).
• No Helper Functions: Do not use helper methods like _buildHeader(). Split components into private classes (e.g., _Header) within the same file (this applies to widgets inside app_ui, NOT feature views).
• Externalize Text: Never hardcode user-facing strings in app_ui. Always pass them as parameters so the feature views can handle translations.
• Configuration Models: If a widget has complex parameters, create a dedicated config class in the same file (e.g., YzPanelConfig).

2.1 Example Implementation

import 'package:flutter/material.dart';

/// Content card for displaying simple text.
///
/// ---
/// @UI: Card | Content
/// @Source: — | Status: manual
/// @Style: Bg: surface | Radius: md
/// @Layout: Padding: md
class YzCard extends StatelessWidget {
  const YzCard({
    required this.title,
    required this.onTap,
    super.key,
  });

  final String title;
  final VoidCallback onTap;

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: onTap,
      child: Container(
        padding: const EdgeInsets.all(AppSpacing.md),
        child: Text(title),
      ),
    );
  }
}