`). Documented; the gallery + goldens wrap cards in a width-constrained parent.
+5. `CardHeader`/`CardFooter` take a `bordered` flag: `true` adds the divider edge (`borderB`/`borderT`) **and** the shadcn-coupled padding (`pb-6`/`pt-6`), matching `[.border-b]:pb-6` / `[.border-t]:pt-6`.
+
+**No-drift scope:** This plan reorders the charter — primitives are being built out before the structure layer. Task 9 updates `docs/superpowers/specs/2026-06-10-flutterbits-charter.md` §8 accordingly and adds `card.dart` as the canonical compound-component template note in `AGENTS.md` §6.
+
+**Deferred (recorded, not silently dropped):** registry promotion (`registry/card.dart` + manifest + `tooling/build_registry.dart`) stays with the registry/CLI plan, exactly as for `button` — Card lives at `apps/gallery/lib/components/ui/card.dart` for now. Per-component docs pages remain a future additive pass (flutterbits docs tab is overview-only by the 2026-06-09 decision; Button is undocumented there too — so Card introduces no docs drift).
+
+---
+
+## File structure
+
+- Create: `apps/gallery/lib/components/ui/card.dart` — `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter` (one file; they are one cohesive copy-paste unit, mirroring shadcn's single `card.tsx`).
+- Create: `apps/gallery/test/card_behavior_test.dart` — structure/layout/theming assertions.
+- Create: `apps/gallery/test/card_golden_test.dart` — golden grid (light LTR / dark LTR / light RTL).
+- Create: `apps/gallery/test/goldens/card_grid_light.png`, `card_grid_dark.png`, `card_grid_rtl.png` (provisional locally; re-baselined from CI artifact).
+- Modify: `apps/gallery/lib/main.dart` — add a Card showcase section so CI compiles the component in the app.
+- Modify: `apps/gallery/test/gallery_smoke_test.dart` — assert a Card example renders.
+- Modify: `docs/superpowers/specs/2026-06-10-flutterbits-charter.md` (§8 sequencing) and `AGENTS.md` (§6 canonical-template note).
+
+---
+
+### Task 1: `Card` root
+
+**Files:**
+- Create: `apps/gallery/lib/components/ui/card.dart`
+- Test: `apps/gallery/test/card_behavior_test.dart`
+
+- [ ] **Step 1: Write the failing test**
+
+```dart
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:flutterwindcss/flutterwindcss.dart';
+import 'package:flutterbits_gallery/components/ui/card.dart';
+
+/// Theme + width frame. Card is block-level (stretches), so it needs a bounded
+/// width — a 320px box stands in for a real layout column.
+Widget _frame(FwTokens tokens, TextDirection dir, Widget child) => FwTheme(
+ tokens: tokens,
+ child: Directionality(
+ textDirection: dir,
+ child: MediaQuery(
+ data: const MediaQueryData(),
+ child: ColoredBox(
+ color: tokens.colors.background,
+ child: Align(
+ alignment: AlignmentDirectional.topStart,
+ child: SizedBox(width: 320, child: child),
+ ),
+ ),
+ ),
+ ),
+);
+
+void main() {
+ testWidgets('Card paints the card token and stacks its children', (t) async {
+ await t.pumpWidget(
+ _frame(
+ FwTokens.light,
+ TextDirection.ltr,
+ const Card(children: [Text('alpha'), Text('beta')]),
+ ),
+ );
+ expect(t.takeException(), isNull);
+ expect(find.text('alpha'), findsOneWidget);
+ expect(find.text('beta'), findsOneWidget);
+ // The card fill uses the `card` semantic token (theme reskin proof).
+ expect(
+ find.byWidgetPredicate(
+ (w) =>
+ w is DecoratedBox &&
+ w.decoration is BoxDecoration &&
+ (w.decoration as BoxDecoration).color == FwTokens.light.colors.card,
+ ),
+ findsOneWidget,
+ );
+ });
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: FAIL — `Card` is undefined (`card.dart` does not exist / no `Card`).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Create `apps/gallery/lib/components/ui/card.dart`:
+
+```dart
+import 'package:flutter/widgets.dart';
+import 'package:flutterwindcss/flutterwindcss.dart';
+
+/// A Material-free, themeable card — shadcn parity. Copy-paste source you own.
+///
+/// **Intention-revealing & composed.** You build a card from sections you pass
+/// in [children] — typically [CardHeader], [CardContent], [CardFooter] — exactly
+/// like shadcn's `
…`. Every value is a `flutterwindcss`
+/// semantic token (`card`, `cardForeground`, `border`), so a pasted theme reskins
+/// it.
+///
+/// **Layout (faithful to shadcn v4 `flex flex-col gap-6 rounded-xl border bg-card
+/// py-6 text-card-foreground shadow-sm`).** The card supplies only *vertical*
+/// padding (`py-6`) and a `gap-6` between sections; **horizontal** padding lives
+/// on each section ([CardHeader]/[CardContent]/[CardFooter] carry `px-6`). That
+/// split is deliberate: it lets a section bleed full-width (an image, or a
+/// bordered divider) while text stays inset.
+///
+/// **Block-level.** The card stretches to its parent's width (like a `
`), so
+/// it MUST be given a bounded width (place it in a constrained column, a
+/// `SizedBox`, or an `Expanded`). In an unbounded-width parent it will assert.
+///
+/// **Non-interactive** (shadcn's card is too). For a tappable card, wrap it
+/// (e.g. in a `GestureDetector`/`Button`); clickability is intentionally not
+/// baked in here.
+class Card extends StatelessWidget {
+ const Card({super.key, required this.children});
+
+ /// The card's sections, stacked vertically with a `gap-6` inside the card's
+ /// `py-6`. Typically [CardHeader], [CardContent], [CardFooter].
+ final List
children;
+
+ @override
+ Widget build(BuildContext context) {
+ final c = context.fw.colors;
+ return FwColumn(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ gap: 6,
+ children: children,
+ ).tw.py(6).bg(c.card).text(c.cardForeground).roundedXl.border(1, color: c.border).shadowSm;
+ }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/gallery/lib/components/ui/card.dart apps/gallery/test/card_behavior_test.dart
+git commit -F
+```
+Message: `feat(card): Card root — themed, block-level, gap-6 section column`
+
+---
+
+### Task 2: `CardTitle` + `CardDescription`
+
+**Files:**
+- Modify: `apps/gallery/lib/components/ui/card.dart`
+- Test: `apps/gallery/test/card_behavior_test.dart`
+
+- [ ] **Step 1: Write the failing test** (append inside `main()`)
+
+```dart
+ testWidgets('CardTitle/CardDescription render their child text', (t) async {
+ await t.pumpWidget(
+ _frame(
+ FwTokens.light,
+ TextDirection.ltr,
+ const Card(
+ children: [
+ CardTitle(Text('Title here')),
+ CardDescription(Text('Subtitle here')),
+ ],
+ ),
+ ),
+ );
+ expect(t.takeException(), isNull);
+ expect(find.text('Title here'), findsOneWidget);
+ expect(find.text('Subtitle here'), findsOneWidget);
+ });
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: FAIL — `CardTitle`/`CardDescription` undefined.
+
+- [ ] **Step 3: Write minimal implementation** (append to `card.dart`)
+
+```dart
+/// The card's title — shadcn `leading-none font-semibold`. Inherits the card's
+/// `cardForeground` text color; pass a `Text` (or any widget) as [child].
+class CardTitle extends StatelessWidget {
+ const CardTitle(this.child, {super.key});
+
+ final Widget child;
+
+ @override
+ Widget build(BuildContext context) => child.tw.weight(FwFontWeight.semibold).leading(1);
+}
+
+/// The card's supporting text — shadcn `text-sm text-muted-foreground`. The
+/// `mutedForeground` override wins over the card's inherited `cardForeground`
+/// for this subtree (nearest `DefaultTextStyle` wins).
+class CardDescription extends StatelessWidget {
+ const CardDescription(this.child, {super.key});
+
+ final Widget child;
+
+ @override
+ Widget build(BuildContext context) =>
+ child.tw.textSize(FwFontSize.sm.px).text(context.fw.colors.mutedForeground);
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/gallery/lib/components/ui/card.dart apps/gallery/test/card_behavior_test.dart
+git commit -F
+```
+Message: `feat(card): CardTitle (semibold/leading-none) + CardDescription (sm/muted)`
+
+---
+
+### Task 3: `CardHeader` + `CardAction` (slots, action grid, bordered divider)
+
+**Files:**
+- Modify: `apps/gallery/lib/components/ui/card.dart`
+- Test: `apps/gallery/test/card_behavior_test.dart`
+
+- [ ] **Step 1: Write the failing test** (append inside `main()`)
+
+```dart
+ testWidgets('CardHeader stacks title+description; no Expanded without an action', (t) async {
+ await t.pumpWidget(
+ _frame(
+ FwTokens.light,
+ TextDirection.ltr,
+ const Card(
+ children: [
+ CardHeader(
+ title: CardTitle(Text('Account')),
+ description: CardDescription(Text('Manage your account')),
+ ),
+ ],
+ ),
+ ),
+ );
+ expect(t.takeException(), isNull);
+ expect(find.text('Account'), findsOneWidget);
+ expect(find.text('Manage your account'), findsOneWidget);
+ // No action → simple stack, no two-column Row/Expanded.
+ expect(find.byType(Expanded), findsNothing);
+ });
+
+ testWidgets('CardHeader with an action lays out two columns (Expanded + action)', (t) async {
+ await t.pumpWidget(
+ _frame(
+ FwTokens.light,
+ TextDirection.ltr,
+ const Card(
+ children: [
+ CardHeader(
+ title: CardTitle(Text('Account')),
+ action: CardAction(Text('Edit')),
+ ),
+ ],
+ ),
+ ),
+ );
+ expect(t.takeException(), isNull);
+ expect(find.text('Account'), findsOneWidget);
+ expect(find.text('Edit'), findsOneWidget);
+ // Action present → title column is wrapped in an Expanded beside the action.
+ expect(find.byType(Expanded), findsOneWidget);
+ });
+
+ testWidgets('bordered CardHeader adds a bottom-border divider', (t) async {
+ await t.pumpWidget(
+ _frame(
+ FwTokens.light,
+ TextDirection.ltr,
+ const Card(
+ children: [
+ CardHeader(title: CardTitle(Text('Account')), bordered: true),
+ ],
+ ),
+ ),
+ );
+ expect(t.takeException(), isNull);
+ // A box whose decoration carries a non-zero bottom border in the `border`
+ // token (the divider).
+ expect(
+ find.byWidgetPredicate((w) {
+ if (w is! DecoratedBox) return false;
+ final d = w.decoration;
+ if (d is! BoxDecoration) return false;
+ final b = d.border;
+ return b != null &&
+ b.bottom.width > 0 &&
+ b.bottom.color == FwTokens.light.colors.border;
+ }),
+ findsWidgets,
+ );
+ });
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: FAIL — `CardHeader`/`CardAction` undefined.
+
+- [ ] **Step 3: Write minimal implementation** (append to `card.dart`)
+
+```dart
+/// The card's top region — shadcn `grid … items-start gap-2 px-6`. Holds a
+/// [title], an optional [description], and an optional [action].
+///
+/// **Action layout (faithful, idiomatic).** shadcn flips to a two-column grid
+/// (`grid-cols-[1fr_auto]`) only when a `CardAction` sibling is present
+/// (`has-data-[slot=card-action]`). Flutter has no `has-[sibling]` selector, so
+/// the action is an explicit slot: with one, the title/description column takes
+/// the free space ([Expanded]) and the [action] sits at the top-end (shadcn
+/// `self-start justify-self-end`); without one, the title/description simply
+/// stack.
+///
+/// Set [bordered] to draw a bottom divider (shadcn `[.border-b]:pb-6` — the
+/// divider implies the extra bottom padding).
+class CardHeader extends StatelessWidget {
+ const CardHeader({
+ super.key,
+ required this.title,
+ this.description,
+ this.action,
+ this.bordered = false,
+ });
+
+ final Widget title;
+ final Widget? description;
+ final Widget? action;
+ final bool bordered;
+
+ @override
+ Widget build(BuildContext context) {
+ final stack = FwColumn(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.start,
+ gap: 2,
+ children: [title, if (description != null) description!],
+ );
+
+ final Widget content =
+ action == null
+ ? stack
+ : FwRow(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [Expanded(child: stack), action!],
+ );
+
+ var styled = content.tw.px(6);
+ if (bordered) {
+ styled = styled.pb(6).borderB(width: 1, color: context.fw.colors.border);
+ }
+ return styled;
+ }
+}
+
+/// An optional action in a [CardHeader] (e.g. a small button or link), pinned to
+/// the header's top-end — shadcn `self-start justify-self-end`. The alignment is
+/// supplied by [CardHeader]; this wrapper marks the role and keeps the call site
+/// readable.
+class CardAction extends StatelessWidget {
+ const CardAction(this.child, {super.key});
+
+ final Widget child;
+
+ @override
+ Widget build(BuildContext context) => child;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/gallery/lib/components/ui/card.dart apps/gallery/test/card_behavior_test.dart
+git commit -F
+```
+Message: `feat(card): CardHeader slots (title/description/action) + bordered divider`
+
+---
+
+### Task 4: `CardContent`
+
+**Files:**
+- Modify: `apps/gallery/lib/components/ui/card.dart`
+- Test: `apps/gallery/test/card_behavior_test.dart`
+
+- [ ] **Step 1: Write the failing test** (append inside `main()`)
+
+```dart
+ testWidgets('CardContent renders its child', (t) async {
+ await t.pumpWidget(
+ _frame(
+ FwTokens.light,
+ TextDirection.ltr,
+ const Card(children: [CardContent(Text('body text'))]),
+ ),
+ );
+ expect(t.takeException(), isNull);
+ expect(find.text('body text'), findsOneWidget);
+ });
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: FAIL — `CardContent` undefined.
+
+- [ ] **Step 3: Write minimal implementation** (append to `card.dart`)
+
+```dart
+/// The card's main content region — shadcn `px-6`. Holds arbitrary [child]
+/// content inside the card's horizontal inset.
+class CardContent extends StatelessWidget {
+ const CardContent(this.child, {super.key});
+
+ final Widget child;
+
+ @override
+ Widget build(BuildContext context) => child.tw.px(6);
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/gallery/lib/components/ui/card.dart apps/gallery/test/card_behavior_test.dart
+git commit -F
+```
+Message: `feat(card): CardContent (px-6 content region)`
+
+---
+
+### Task 5: `CardFooter` (+ bordered top divider)
+
+**Files:**
+- Modify: `apps/gallery/lib/components/ui/card.dart`
+- Test: `apps/gallery/test/card_behavior_test.dart`
+
+- [ ] **Step 1: Write the failing test** (append inside `main()`)
+
+```dart
+ testWidgets('CardFooter renders children in a row', (t) async {
+ await t.pumpWidget(
+ _frame(
+ FwTokens.light,
+ TextDirection.ltr,
+ const Card(
+ children: [
+ CardFooter(children: [Text('Cancel'), Text('Save')]),
+ ],
+ ),
+ ),
+ );
+ expect(t.takeException(), isNull);
+ expect(find.text('Cancel'), findsOneWidget);
+ expect(find.text('Save'), findsOneWidget);
+ });
+
+ testWidgets('bordered CardFooter adds a top-border divider', (t) async {
+ await t.pumpWidget(
+ _frame(
+ FwTokens.light,
+ TextDirection.ltr,
+ const Card(
+ children: [
+ CardFooter(bordered: true, children: [Text('Save')]),
+ ],
+ ),
+ ),
+ );
+ expect(t.takeException(), isNull);
+ expect(
+ find.byWidgetPredicate((w) {
+ if (w is! DecoratedBox) return false;
+ final d = w.decoration;
+ if (d is! BoxDecoration) return false;
+ final b = d.border;
+ return b != null && b.top.width > 0 && b.top.color == FwTokens.light.colors.border;
+ }),
+ findsWidgets,
+ );
+ });
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: FAIL — `CardFooter` undefined.
+
+- [ ] **Step 3: Write minimal implementation** (append to `card.dart`)
+
+```dart
+/// The card's bottom region — shadcn `flex items-center px-6`. Lays [children]
+/// out in a vertically-centered row (typically actions). **No default gap**
+/// (faithful to shadcn) — space the children yourself (e.g. an `FwRow` gap, or
+/// a `Spacer`).
+///
+/// Set [bordered] to draw a top divider (shadcn `[.border-t]:pt-6` — the divider
+/// implies the extra top padding).
+class CardFooter extends StatelessWidget {
+ const CardFooter({super.key, required this.children, this.bordered = false});
+
+ final List children;
+ final bool bordered;
+
+ @override
+ Widget build(BuildContext context) {
+ var styled =
+ FwRow(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.center,
+ children: children,
+ ).tw.px(6);
+ if (bordered) {
+ styled = styled.pt(6).borderT(width: 1, color: context.fw.colors.border);
+ }
+ return styled;
+ }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/gallery/lib/components/ui/card.dart apps/gallery/test/card_behavior_test.dart
+git commit -F
+```
+Message: `feat(card): CardFooter (items-center row) + bordered top divider`
+
+---
+
+### Task 6: RTL + theming reskin behavior tests
+
+**Files:**
+- Test: `apps/gallery/test/card_behavior_test.dart`
+
+- [ ] **Step 1: Write the failing test** (append inside `main()`)
+
+```dart
+ testWidgets('renders under RTL with no overflow/exception', (t) async {
+ await t.binding.setSurfaceSize(const Size(400, 400));
+ addTearDown(() => t.binding.setSurfaceSize(null));
+ await t.pumpWidget(
+ _frame(
+ FwTokens.light,
+ TextDirection.rtl,
+ const Card(
+ children: [
+ CardHeader(
+ title: CardTitle(Text('عنوان')),
+ description: CardDescription(Text('وصف')),
+ action: CardAction(Text('تعديل')),
+ bordered: true,
+ ),
+ CardContent(Text('محتوى')),
+ CardFooter(bordered: true, children: [Text('حفظ')]),
+ ],
+ ),
+ ),
+ );
+ expect(t.takeException(), isNull);
+ expect(find.text('عنوان'), findsOneWidget);
+ expect(find.text('تعديل'), findsOneWidget);
+ });
+
+ testWidgets('reskins with the active theme (dark card token)', (t) async {
+ await t.pumpWidget(
+ _frame(
+ FwTokens.dark,
+ TextDirection.ltr,
+ const Card(children: [CardContent(Text('x'))]),
+ ),
+ );
+ expect(t.takeException(), isNull);
+ expect(
+ find.byWidgetPredicate(
+ (w) =>
+ w is DecoratedBox &&
+ w.decoration is BoxDecoration &&
+ (w.decoration as BoxDecoration).color == FwTokens.dark.colors.card,
+ ),
+ findsOneWidget,
+ );
+ // The light card token must NOT appear (proves it actually reskinned).
+ expect(
+ find.byWidgetPredicate(
+ (w) =>
+ w is DecoratedBox &&
+ w.decoration is BoxDecoration &&
+ (w.decoration as BoxDecoration).color == FwTokens.light.colors.card,
+ ),
+ findsNothing,
+ );
+ });
+```
+
+- [ ] **Step 2: Run test to verify it fails or passes**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: PASS (the implementation already supports these; this task locks the behavior with regression tests). If the RTL test reports a RenderFlex overflow, that is a real bug — fix the layout (do not loosen the assertion).
+
+- [ ] **Step 3: (only if a test failed) fix the implementation**
+
+If the dark-token test fails because `FwTokens.dark.colors.card == FwTokens.light.colors.card` for the stock theme, switch the assertion to a token that differs between brightnesses (`background`) — but verify the stock `FwTokens` card values first with a one-off `expect(FwTokens.light.colors.card == FwTokens.dark.colors.card, isFalse)` and keep `card` if they differ.
+
+- [ ] **Step 4: Run the full behavior suite**
+
+Run: `cd apps/gallery && flutter test test/card_behavior_test.dart`
+Expected: PASS (all cases).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/gallery/test/card_behavior_test.dart
+git commit -F
+```
+Message: `test(card): RTL composition + theme-reskin regression coverage`
+
+---
+
+### Task 7: Golden grid (light / dark / RTL)
+
+**Files:**
+- Create: `apps/gallery/test/card_golden_test.dart`
+- Create (provisional, then re-baselined on CI): `apps/gallery/test/goldens/card_grid_{light,dark,rtl}.png`
+
+- [ ] **Step 1: Write the golden test**
+
+```dart
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:flutterwindcss/flutterwindcss.dart';
+import 'package:flutterbits_gallery/components/ui/card.dart';
+
+/// Theme frame: FwTheme + Directionality + MediaQuery + background surface. The
+/// grid is wrapped in a RepaintBoundary so [matchesGoldenFile] captures a clean
+/// boundary. Cards are block-level (stretch), so each is width-constrained.
+Widget _frame(FwTokens tokens, TextDirection dir, Widget child) => FwTheme(
+ tokens: tokens,
+ child: Directionality(
+ textDirection: dir,
+ child: MediaQuery(
+ data: const MediaQueryData(),
+ child: ColoredBox(
+ color: tokens.colors.background,
+ child: Align(
+ alignment: AlignmentDirectional.topStart,
+ child: Padding(padding: const EdgeInsets.all(16), child: child),
+ ),
+ ),
+ ),
+ ),
+);
+
+Widget _grid() => RepaintBoundary(
+ key: const ValueKey('card_grid'),
+ child: SizedBox(
+ width: 320,
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: const [
+ // 1. Full card: header (title+description) + content + footer.
+ Card(
+ children: [
+ CardHeader(
+ title: CardTitle(Text('Create project')),
+ description: CardDescription(Text('Deploy your new project in one click.')),
+ ),
+ CardContent(Text('Project configuration and details go here.')),
+ CardFooter(children: [Text('Cancel '), Text('Deploy')]),
+ ],
+ ),
+ SizedBox(height: 16),
+ // 2. Header with an action + bordered header & footer dividers.
+ Card(
+ children: [
+ CardHeader(
+ title: CardTitle(Text('Notifications')),
+ description: CardDescription(Text('Choose what you get notified about.')),
+ action: CardAction(Text('Manage')),
+ bordered: true,
+ ),
+ CardContent(Text('Email, push, and SMS preferences.')),
+ CardFooter(bordered: true, children: [Text('Save preferences')]),
+ ],
+ ),
+ ],
+ ),
+ ),
+);
+
+void main() {
+ const surfaceSize = Size(420, 700);
+
+ testWidgets('card grid — light LTR', (t) async {
+ await t.binding.setSurfaceSize(surfaceSize);
+ addTearDown(() => t.binding.setSurfaceSize(null));
+ await t.pumpWidget(_frame(FwTokens.light, TextDirection.ltr, _grid()));
+ await expectLater(
+ find.byKey(const ValueKey('card_grid')),
+ matchesGoldenFile('goldens/card_grid_light.png'),
+ );
+ });
+
+ testWidgets('card grid — dark LTR', (t) async {
+ await t.binding.setSurfaceSize(surfaceSize);
+ addTearDown(() => t.binding.setSurfaceSize(null));
+ await t.pumpWidget(_frame(FwTokens.dark, TextDirection.ltr, _grid()));
+ await expectLater(
+ find.byKey(const ValueKey('card_grid')),
+ matchesGoldenFile('goldens/card_grid_dark.png'),
+ );
+ });
+
+ testWidgets('card grid — light RTL (directional padding/dividers mirror)', (t) async {
+ await t.binding.setSurfaceSize(surfaceSize);
+ addTearDown(() => t.binding.setSurfaceSize(null));
+ await t.pumpWidget(_frame(FwTokens.light, TextDirection.rtl, _grid()));
+ await expectLater(
+ find.byKey(const ValueKey('card_grid')),
+ matchesGoldenFile('goldens/card_grid_rtl.png'),
+ );
+ });
+}
+```
+
+- [ ] **Step 2: Run to verify it fails (no goldens yet)**
+
+Run: `cd apps/gallery && flutter test test/card_golden_test.dart`
+Expected: FAIL — golden files do not exist.
+
+- [ ] **Step 3: Generate provisional local goldens**
+
+Run: `cd apps/gallery && flutter test --update-goldens test/card_golden_test.dart`
+Then **open the three PNGs** in `apps/gallery/test/goldens/` and eyeball-verify layout/shape (text renders as deterministic boxes in the test font — check structure: rounded card, dividers in the bordered card, action at the end, RTL mirrors the inset/dividers). Provisional only — CI Linux is authoritative (next step).
+
+- [ ] **Step 4: Run to verify the provisional goldens pass locally**
+
+Run: `cd apps/gallery && flutter test test/card_golden_test.dart`
+Expected: PASS (locally).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/gallery/test/card_golden_test.dart apps/gallery/test/goldens/card_grid_light.png apps/gallery/test/goldens/card_grid_dark.png apps/gallery/test/goldens/card_grid_rtl.png
+git commit -F
+```
+Message: `test(card): golden grid (light/dark/RTL) — provisional, CI Linux authoritative`
+
+> Re-baselining on CI happens in Task 8 after the PR is open (Windows goldens are known to differ from CI Linux — Button precedent).
+
+---
+
+### Task 8: Gallery integration + smoke test
+
+**Files:**
+- Modify: `apps/gallery/lib/main.dart`
+- Modify: `apps/gallery/test/gallery_smoke_test.dart`
+
+- [ ] **Step 1: Update the smoke test (failing) to expect a Card example**
+
+In `apps/gallery/test/gallery_smoke_test.dart`, add an assertion after the existing `find.text('primary')` check:
+
+```dart
+ expect(find.text('Create project'), findsWidgets);
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `cd apps/gallery && flutter test test/gallery_smoke_test.dart`
+Expected: FAIL — `'Create project'` not found (no Card in the gallery yet).
+
+- [ ] **Step 3: Add a Card showcase to `main.dart`**
+
+In `apps/gallery/lib/main.dart`, import the card and add a Card section to the showcase. Replace the `home:` `Column`'s child list so it shows the existing button rows **and** a cards section below them. Concretely, add this import at the top:
+
+```dart
+import 'components/ui/card.dart';
+```
+
+and, inside the `Column(children: [...])` in `home:` (after the existing button `Padding` blocks, before the closing `]`), insert:
+
+```dart
+ const SizedBox(height: 24),
+ const Text('Cards').tw.textSize(20).weight(FwFontWeight.bold),
+ const SizedBox(height: 12),
+ SizedBox(
+ width: 320,
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: const [
+ Card(
+ children: [
+ CardHeader(
+ title: CardTitle(Text('Create project')),
+ description: CardDescription(
+ Text('Deploy your new project in one click.'),
+ ),
+ ),
+ CardContent(Text('Project configuration goes here.')),
+ CardFooter(children: [Text('Deploy')]),
+ ],
+ ),
+ SizedBox(height: 16),
+ Card(
+ children: [
+ CardHeader(
+ title: CardTitle(Text('Notifications')),
+ action: CardAction(Text('Manage')),
+ bordered: true,
+ ),
+ CardContent(Text('Email and push preferences.')),
+ ],
+ ),
+ ],
+ ),
+ ),
+```
+
+> Note: `const Text('Cards').tw…` — `.tw` returns a non-const `FwStyled`, so drop `const` on that one line if the analyzer flags it (`Text('Cards').tw.textSize(20).weight(FwFontWeight.bold)`).
+
+- [ ] **Step 4: Run the smoke test + analyze**
+
+Run: `cd apps/gallery && flutter test test/gallery_smoke_test.dart`
+Expected: PASS.
+Run: `cd apps/gallery && flutter analyze --fatal-infos --fatal-warnings`
+Expected: No issues.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/gallery/lib/main.dart apps/gallery/test/gallery_smoke_test.dart
+git commit -F
+```
+Message: `feat(gallery): showcase Card examples; smoke-test the card`
+
+---
+
+### Task 9: No-drift — charter §8 reorder + AGENTS §6 canonical-template note
+
+**Files:**
+- Modify: `docs/superpowers/specs/2026-06-10-flutterbits-charter.md`
+- Modify: `AGENTS.md`
+
+- [ ] **Step 1: Update charter §8 sequencing**
+
+In `docs/superpowers/specs/2026-06-10-flutterbits-charter.md` §8, after the numbered decomposition list, add a paragraph recording the reorder (do not delete the existing list — it stays the umbrella plan):
+
+```markdown
+> **Sequencing update (2026-06-15):** after `Button` proved the component-authoring stack end-to-end (PR #45–#47), the **primitives catalog (§3.2) is being built out before the structure layer (§2 above)** — lower-risk, reuses the proven pattern, and several structure pieces (e.g. `ThemeToggle` → `Switch`) depend on primitives anyway. `Card` is the first post-`Button` primitive and the canonical template for *compound, non-interactive* components. The structure-and-routing spec remains next-in-line as an epic; this is a sequencing change, not a scope change.
+```
+
+- [ ] **Step 2: Add the canonical-template note to AGENTS.md §6**
+
+In `AGENTS.md` §6, find the sentence about `registry/button.dart` becoming the canonical template and append a sibling note (keep the existing text):
+
+```markdown
+> `apps/gallery/lib/components/ui/card.dart` is the canonical template for **compound, non-interactive** components (composed subcomponents, slot-based regions, theme-resolved tokens, no interaction state machine), complementing `button.dart` (the canonical **interactive** component). Mirror whichever matches the component you are authoring.
+```
+
+- [ ] **Step 3: Verify no other doc falsified**
+
+Run: `git grep -n "coming soon" apps/docs/content/docs/flutterbits` — confirm the flutterbits docs tab is still overview-only (Button is undocumented there too, so Card adds no docs drift). No edit needed; this is a verification step.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/superpowers/specs/2026-06-10-flutterbits-charter.md AGENTS.md
+git commit -F
+```
+Message: `docs: record primitives-before-structure reorder + card canonical template (no-drift)`
+
+---
+
+### Task 10: Final verification + PR
+
+**Files:** none (verification + integration)
+
+- [ ] **Step 1: Full analyze (zero-warning bar)**
+
+Run: `cd apps/gallery && flutter analyze --fatal-infos --fatal-warnings`
+Expected: `No issues found!`
+
+- [ ] **Step 2: Format check**
+
+Run: `dart format --line-length 100 --set-exit-if-changed apps/gallery/lib/components/ui/card.dart apps/gallery/test/card_behavior_test.dart apps/gallery/test/card_golden_test.dart apps/gallery/lib/main.dart apps/gallery/test/gallery_smoke_test.dart`
+Expected: no changes (already formatted). If it reformats, re-run without `--set-exit-if-changed`, then re-commit.
+
+- [ ] **Step 3: Full gallery test suite**
+
+Run: `cd apps/gallery && flutter test`
+Expected: all PASS (button + card behavior, both golden suites, smoke). Goldens pass locally; CI will re-baseline.
+
+- [ ] **Step 4: Open the PR**
+
+```bash
+git push -u origin feat/flutterbits-card
+gh pr create --title "feat(card): Card primitive (shadcn v4) + gallery showcase" --body-file
+```
+PR body: summary, the design decisions (composition; header slots vs `has-[sibling]`; block-level width; bordered dividers), the shadcn-v4 class mapping table, test coverage, and a note that goldens are provisional pending the CI Linux re-baseline. End with the Claude Code trailer.
+
+- [ ] **Step 5: Re-baseline goldens on CI Linux (the Button precedent recipe)**
+
+Wait for the `gallery` CI job. If the golden step fails on the Linux renders (expected — Windows AA differs):
+
+```bash
+gh run download -n gallery-golden-failures -D /tmp/card-goldens
+```
+
+The `*_testImage.png` files are the authoritative Linux renders. Copy each over its baseline (strip the `_testImage` suffix):
+- `card_grid_light_testImage.png` → `apps/gallery/test/goldens/card_grid_light.png`
+- `card_grid_dark_testImage.png` → `apps/gallery/test/goldens/card_grid_dark.png`
+- `card_grid_rtl_testImage.png` → `apps/gallery/test/goldens/card_grid_rtl.png`
+
+Eyeball-verify shape/layout (test font = boxes), then:
+
+```bash
+git add apps/gallery/test/goldens/card_grid_light.png apps/gallery/test/goldens/card_grid_dark.png apps/gallery/test/goldens/card_grid_rtl.png
+git commit -F # "test(card): re-baseline goldens on CI Linux (authoritative platform)"
+git push
+```
+
+- [ ] **Step 6: Confirm green + merge**
+
+Run: `gh pr checks` until all green, then:
+```bash
+gh pr merge --merge --delete-branch
+git checkout main && git pull
+```
+
+---
+
+## Self-review (completed against the spec/grounding)
+
+- **Spec coverage:** every shadcn v4 Card part is implemented — Card (T1), CardTitle/CardDescription (T2), CardHeader + CardAction + action-grid + `[.border-b]` (T3), CardContent (T4), CardFooter + `[.border-t]` (T5). The `gap-6`/`py-6`/`px-6` split, `rounded-xl`, `border`, `bg-card`/`text-card-foreground`, `shadow-sm`, `leading-none font-semibold`, `text-sm text-muted-foreground` all mapped in the grounding table and used verbatim in the steps.
+- **AGENTS.md rules:** semantic tokens only (no literal colors — Card needs none, not even the transparent literal); directional (`px`/`ps`/`pe`/`borderB`/`borderT`/`CrossAxisAlignment.start`); `package:flutter/widgets.dart` only (no Material — passes the gallery arch-guard); `.tw` single-box styling, layout via `FwColumn`/`FwRow`; one component file; golden coverage (variant-equivalent configs × brightness × RTL); rendered in `apps/gallery`.
+- **Type consistency:** `Card.children` (List), `CardHeader.title/description/action/bordered`, `CardFooter.children/bordered`, `CardTitle(child)`/`CardDescription(child)`/`CardContent(child)`/`CardAction(child)` positional — used identically across implementation, tests, gallery, and goldens.
+- **Placeholder scan:** none — every step has complete code or an exact command + expected output.
+- **Deviation honesty:** the one deviation (explicit header slots vs `has-[sibling]` grid) is a faithful-result/idiomatic-means choice with the mechanism stated, not a capability reduction (raises the bar — AGENTS.md §12). Non-interactive Card and block-level width are documented limitations with the compose-to-extend path, not silent gaps.
diff --git a/docs/superpowers/specs/2026-06-10-flutterbits-charter.md b/docs/superpowers/specs/2026-06-10-flutterbits-charter.md
index d8278a2..dd26fb5 100644
--- a/docs/superpowers/specs/2026-06-10-flutterbits-charter.md
+++ b/docs/superpowers/specs/2026-06-10-flutterbits-charter.md
@@ -167,6 +167,8 @@ This charter is the umbrella. Implementation is decomposed into specs, each its
**First vertical slice (proves the whole stack end-to-end):** `Layout` + `Screen` + routing + `Button` + `ThemeToggle`, rendered in **`apps/gallery`** — a **new** flutterbits component showcase + golden/compile target, created with this slice and kept separate from the engine's `apps/example` (decision 2026-06-10). `ThemeToggle` is the chosen first concrete component — tiny, pure "feel good," and it forces every layer to play together (`Layout` owning theme → the `Switch` primitive → semantic-token reskin → the engine's `FwAnimatedTheme` transition).
+> **Sequencing update (2026-06-15):** after `Button` proved the component-authoring stack end-to-end (PRs #45–#47 — `apps/gallery` scaffold, CI gating, canonical audit), the **primitives catalog (§3.2) is being built out before the structure layer (item 2 above)**. Rationale: it is lower-risk, reuses the proven component pattern, and several structure pieces depend on primitives anyway (e.g. `ThemeToggle` → a `Switch` primitive). `Card` (2026-06-15) is the first post-`Button` primitive and the canonical template for **compound, non-interactive** components (composed subcomponents, slot-based regions; see `apps/gallery/lib/components/ui/card.dart`). The structure-and-routing spec remains next-in-line as an epic — this is a **sequencing** change, not a scope change.
+
---
## 9. Open questions (deferred, by explicit decision)