Shadcn Flutter Registry Documentation

This skill helps you write and maintain high-quality CHANGELOG entries and comprehensive Dart/Flutter API documentation for the shadcn-flutter-registry project. It enforces Keep a Changelog structure, analyzer-friendly formatting, and comprehensive component testing guidelines.

What This Skill Does

Instructions for AI Agent

CHANGELOG Maintenance

When updating CHANGELOG.md:

1. **Structure**: Use Keep a Changelog format with version headers (no dates) and categories: Added, Changed, Deprecated, Removed, Fixed, Security, Breaking Changes

2. **Entry Format**: Write bullets as `- Short imperative summary (PR 1234, @author)` or `(commit abcdef1, @author)`

3. **When to Update**: Update in the same PR for any user-visible change (API, behavior, UI, DX). Omit only purely internal refactors.

4. **Breaking Changes**: Must include migration guide with old → new examples (2-6 steps) and version requirements

5. **Retroactive Updates** (when changelog missing):

- Identify PR/commit that introduced change

- If commit message is descriptive, derive bullet from it

- If vague: compute diff size (inserted + deleted lines)

- If < 1000 lines: parse diff and create bullets mentioning affected APIs/files

- If >= 1000 lines: write brief summary + "Manual review required (diff >= 1000 lines)"

- Detect API/behavior changes; mark breaking changes with migration guide

Dart/Flutter API Documentation

For all public APIs (classes, constructors, methods, functions, typedefs, fields):

1. **Critical Formatting Rules**:

- Use `///` triple-slash comments

- **Always wrap generic types in backticks**: `` `List<int>` ``, `` `ValueChanged<T?>` ``, `` `Map<FormKey, FutureOr<ValidationResult?>>` ``

- Link symbols without generics: `[AnimatedBuilder]`, `[SelectController]`

- Show generics in inline code: `` `SelectController<T>` `` not `[SelectController<T>]`

- Use fenced code blocks with `dart` for examples

- Avoid HTML and angle brackets in prose

2. **Standard Section Order**:

- One-sentence summary

- Overview/Details paragraph

- Parameters (bulleted): `- [paramName] (`Type`, qualifiers): Description`

- Returns

- Errors/Assertions

- Example(s): fenced `dart` code

- Notes/Edge cases

- See also (bracket links)

3. **Class Documentation Template**:

```dart

/// A concise one-sentence summary of what this component does.

///

/// Longer overview explaining when and why to use it. Mention key behaviors,

/// lifecycle, state interactions, and customization points.

///

/// Parameters:

/// - [param1] (`Type`, required): What it does.

/// - [onChanged] (`ValueChanged<T>?`, optional): When it fires and how.

///

/// Example:

/// ```dart

/// MyComponent(

/// value: 42,

/// onChanged: (v) => print(v),

/// )

/// ```

class MyComponent<T> extends StatelessWidget {

// ...

}

```

4. **Constructor Documentation**:

- Default constructor: "Creates a [ClassName]."

- Named constructor: "Creates a [ClassName] with <mode> behavior."

- Always document parameters with types, defaults, and semantics

- Include runnable examples

5. **Common Patterns**:

- Controlled components: document `controller` as source of truth when provided

- Theming: wrap generics in backticks: `` `ComponentTheme<TrackerTheme>` ``

- Animation builders: `` `AnimatedChildBuilder<T>` ``

- Collections: `` `List<T>` ``, `` `Iterable<T>` ``, `` `Predicate<T>` ``

6. **Quality Checks**:

- Run `dart analyze` - zero warnings expected

- No `unintended_html_in_doc_comment` warnings

- All generic types wrapped in backticks

- Examples are runnable and use `const` where appropriate

Component Testing Guidelines

Every public component must have comprehensive widget tests:

1. **Test Coverage Checklist**:

- Visibility and rendering (renders without exceptions, expected default state)

- Size and layout (respects constraints, expands/shrinks correctly)

- Position and alignment (aligns as configured)

- Interactivity and gestures (tap/click/hover trigger callbacks)

- Focus and keyboard (focus traversal, keyboard shortcuts)

- Scrolling and overflow (scrolls when content exceeds bounds)

- Theming and variants (light/dark, high-contrast, sizes/intent)

- RTL and internationalization (layout mirrors, text scales)

- Responsiveness (small/large screens, orientation changes)

- Accessibility and semantics (proper roles, labels, tap targets)

- Error states and assertions (invalid configs throw meaningful errors)

- Animation timing and transitions (runs with expected curves/durations)

2. **Test File Structure**:

- Location: `test/<package or area>/<component_name>_test.dart`

- One primary file per component

- Small, focused tests that assert behavior and user-visible outcomes

3. **Minimal Test Template**:

```dart

import 'package:flutter_test/flutter_test.dart';

import 'package:flutter/material.dart';

void main() {

testWidgets('renders and is visible', (tester) async {

await tester.pumpWidget(

MaterialApp(

theme: ThemeData.light(),

home: Scaffold(body: YourComponent()),

),

);

expect(find.byType(YourComponent), findsOneWidget);

});

testWidgets('responds to tap', (tester) async {

var tapped = false;

await tester.pumpWidget(

MaterialApp(home: YourComponent(onTap: () => tapped = true))

);

await tester.tap(find.byType(YourComponent));

await tester.pumpAndSettle();

expect(tapped, isTrue);

});

}

```

Examples

Good CHANGELOG Entry

```markdown

Added

Breaking Changes

Migration guide:

1. Replace `WidgetX` with `WidgetY`.

2. Rename styles from `x-` to `y-` in CSS.

```

Good Documentation

```dart

/// A button that triggers an action when pressed.

///

/// Parameters:

/// - [onPressed] (`VoidCallback?`, optional): Called when button is tapped.

/// - [child] (`Widget`, required): The button's content.

/// - [style] (`ButtonStyle?`, optional, default: primary): Visual styling.

///

/// Example:

/// ```dart

/// Button(

/// onPressed: () => print('tapped'),

/// child: const Text('Click me'),

/// )

/// ```

```

Constraints