CoUI Flutter Quick Reference (v0.127 bare-widget standard)

기준: coui v0.127.15 (Co 접두어 제거된 de-prefix 세대. kobic development는 v0.127.15+ 서브모듈로 마이그레이션 완료). 💡 See CLAUDE.md for the full guide. This document is a quick reference; the cc-coui plugin's per-component skills (coui-button, coui-input, coui-text-field, coui-badge, coui-gap, …) are the source of truth — check there when in doubt.

Authoritative Source#

All signatures below are verified against the kobic-vendored CoUI:

• Components: package/coui/packages/coui_flutter/lib/src/components/**/co_*.dart
• Contracts/enums: package/coui/packages/coui_flutter + coui_core contracts
• Import everything through the core barrel:

// ✅ CORRECT: single barrel import
import 'package:core/core.dart';

// ❌ WRONG: never import coui_flutter directly in feature/app code
import 'package:coui_flutter/coui_flutter.dart';

CoUI widgets are re-exported through package:core/core.dart. Feature and app code must never depend on package:coui_flutter directly.

Components are bare <X> with variant: / size: enums#

CoUI follows a single unified widget per component (Button, Badge, TextField, Icon, Gap) — as of v0.127 there is no Co prefix on any widget class; Co<X> names were removed in a hard break and no longer compile (no aliases). There are no named constructors like Button.primary() / PrimaryBadge / ButtonStyle.ghost(). Visual style is selected via the variant: (and size:) enum parameters; chrome overrides flow through the single style object (buttonStyle: / badgeStyle: / inputStyle: / textFieldStyle: / iconStyle:).

Buttons — Button#

class Button extends StatefulWidget {
  const Button({
    required this.child,
    super.key,
    this.variant = CoreButtonVariant.primary,
    this.size = CoreComponentSize.md,
    this.shape = CoreButtonShape.rectangle,
    this.leading,
    this.trailing,
    this.onPressed,
    this.enabled,
    this.buttonStyle,
    this.expanded = false,
    // ... interaction callbacks
  });
}

CoreButtonVariant#

primary · secondary · outline · ghost · link · text · plain · destructive · card · menu · menubar · fixed

CoreComponentSize (shared by all components)#

xs · sm · md (default) · lg · xl

ButtonSize.medium, ButtonSize.normal, ButtonDensity do not exist.

Usage#

// Primary action — uses defaults (variant: primary, size: md)
Button(
  expanded: true,
  enabled: state.isValid,
  onPressed: () => context.read<MyBloc>().add(const MyEvent.submitted()),
  child: const Text('저장'),
)

// Secondary / cancel — dot-shorthand on the enum
Button(
  variant: .ghost,
  onPressed: () => context.pop(),
  child: const Text('취소'),
)

// Destructive
Button(
  variant: .destructive,
  onPressed: onDelete,
  child: const Text('삭제'),
)

// Sized + leading icon
Button(
  variant: .outline,
  size: .sm,
  leading: const Icon(LucideIcons.pencil),
  onPressed: onEdit,
  child: const Text('편집'),
)

// Icon-only via shape
Button(
  variant: .ghost,
  shape: .square,
  onPressed: onMore,
  child: const Icon(LucideIcons.ellipsisVertical),
)

Chrome / dimensional overrides go through buttonStyle: CoreButtonStyle(...), not through removed ButtonStyle.primary().copyWith(...). There is no separate ButtonSize/ButtonDensity scale — size is CoreComponentSize (xs/sm/md/lg/xl) and dimensional tweaks (padding, height, etc.) flow through buttonStyle.

Badge — Badge#

class Badge extends StatefulWidget {
  const Badge({
    this.variant = CoreBadgeVariant.defaultVariant, // primary
    required this.child,
    super.key,
    this.size = CoreComponentSize.sm,
    this.leading,
    this.trailing,
    this.onPressed,
    this.badgeStyle,
  });
}

CoreBadgeVariant#

primary (default) · secondary · outline · destructive

Usage#

// Positive / active status
const Badge(child: Text('판매중'))               // variant defaults to primary

// Negative status
const Badge(variant: .destructive, child: Text('판매중지'))

// With a leading icon
Badge(
  variant: .secondary,
  leading: const Icon(LucideIcons.eye),
  child: const Text('미리보기'),
)

// Conditional
book.isActive
    ? const Badge(child: Text('판매중'))
    : const Badge(variant: .destructive, child: Text('판매중지'))

PrimaryBadge / DestructiveBadge / CoBadge do not exist — use Badge(variant: ...).

Icons — Icon#

class Icon extends StatefulWidget {
  const Icon(this.icon, {super.key, this.iconStyle});
}

Icons come from Iconify icon sets re-exported by CoUI — kobic primarily uses LucideIcons and RadixIcons (bare names, no Co prefix in v0.127).

const Icon(LucideIcons.trash)
const Icon(RadixIcons.chevronDown)

// Size / color override
Icon(
  LucideIcons.circleAlert,
  iconStyle: CoreIconStyle(size: 16, color: context.appColors.error.toValue()),
)

CoIcon, CoLucideIcons, CoRadixIcons no longer compile (v0.127 de-prefix). HeroIcon (the standalone heroicons package widget) is not used — CoUI's own HeroIcons icon set (a StyledIconName, via the CoUI Icon widget) is the canonical way to render HeroIcons glyphs if needed.

Text Input — Input (bare) vs TextField (labelled)#

Input is the bare single-line text-entry primitive (type, placeholder, value, onChanged, validation/length/range attributes) — it has no label / prefix / suffix slots. For a labelled field with prefix / suffix / errorText / built-in clear-or-password-toggle affordances, use TextField. There is no FormTextField, and there is no bare InputFeature leading/trailing widget-building API — the platform-neutral data model is CoreInputFeature, and it only has two factories: .clear() and .passwordToggle() (arbitrary leading/trailing icons go through TextField's own prefix/suffix parameters, not through a feature).

// Input — bare text-entry primitive, no label
Input(
  type: CoreInputType.email,
  placeholder: '이메일을 입력하세요',
  value: state.email,
  onChanged: (value) =>
      context.read<MyBloc>().add(MyEvent.emailChanged(value)),
)

// Error variant
Input(
  type: CoreInputType.email,
  placeholder: '이메일',
  variant: CoreInputVariant.error,
  onChanged: (value) => ...,
)

// TextField — labelled field with label / prefix / errorText / built-in features
TextField(
  label: '이메일',
  placeholder: const Text('이메일을 입력하세요'),
  controller: controller,
  keyboardType: TextInputType.emailAddress,
  prefix: const Icon(LucideIcons.mail),
  errorText: state.emailError,
  onChanged: (value) => ...,
)

// TextField — password with the built-in visibility-toggle feature
TextField(
  label: '비밀번호',
  obscureText: true,
  features: const [CoreInputFeature.passwordToggle()],
  onChanged: (value) => ...,
)

Input chrome/dimensional overrides go through inputStyle: CoreInputStyle(...) (no size:/shape: parameter). CoreInputType: text, password, email, number, tel, url, search. TextField overrides go through textFieldStyle: CoreTextFieldStyle(...); size via size: .md (CoreComponentSize). See coui-input / coui-text-field for the complete parameter set.

Typography — context.textStyles#

context.textStyles returns the CoUI Typography from the current theme. Use its style getters directly; never use context.theme.typography or the removed Text().lg.bold chaining.

// ✅ Project standard
style: context.textStyles.lgSemibold
style: context.textStyles.smSemibold
style: context.textStyles.baseMedium

// ✅ copyWith composition
style: context.textStyles.lgSemibold.copyWith(
  color: context.appColors.neutral5,
)

Common getters (<size><weight>)#

xsSemibold · xsBold · smNormal · smSemibold · smBold · baseNormal · baseSemibold · baseBold · lgNormal · lgSemibold · lgBold · xlNormal · xlSemibold · xlBold · x2lBold · x3lSemibold … (plus Material-3 semantic getters such as titleMedium, bodyMedium, labelLargeSemiBold).

Size scale (approx px)#

Text('제목', style: context.textStyles.lgSemibold)
Text('본문', style: context.textStyles.baseNormal)
Text('캡션', style: context.textStyles.smNormal)

Spacing — Gap (token constructors / gapStyle)#

Prefer the Gap.spaceN() token constructors. For non-token sizes, a cross-axis extent, or a fill color use the single gapStyle: CoreGapStyle(...) slot. Insets, Spacing, and older CoGap forms are removed/legacy. As of v0.127 there is no Co prefix — the widget is bare Gap; the bare Gap(size: CoreSpace.spaceN) constructor-level size: form (pre-v0.127) is also gone — use the token constructor or gapStyle: instead.

class Gap extends StatelessWidget {
  const Gap({this.gapStyle, super.key});
  // plus const Gap.spaceN() per CoreSpace.spaceN, and Gap.expand(...)
}

// ✅ v0.127 standard — token constructors
const Gap.space4()    // 4px
const Gap.space8()    // 8px
const Gap.space16()   // 16px
const Gap.space24()   // 24px

// ✅ Non-token size / cross extent / fill color via gapStyle
const Gap(gapStyle: CoreGapStyle(size: 18))

// EdgeInsets / padding also use CoreSpace tokens
Padding(
  padding: const EdgeInsets.symmetric(horizontal: CoreSpace.space16),
  child: child,
)

CoreSpace tokens (double, logical px)#

space0 · space2 · space4 · space6 · space8 · space10 · space12 · space14 · space16 · space20 · space24 · space28 · space32 … (2px steps to 16, then 4px steps). The token name is the pixel value. Each value has a matching Gap.spaceN() constructor.

Loading / Skeleton Patterns#

// Skeleton loading (entire widget)
widget.skeletonizer(enabled: state.isLoading)

// Conditional loading (spinner)
widget.loadingOr(
  isLoading: state.isLoading,
  loadingWidget: const CircularProgressIndicator(),
)

// Empty state handling
listWidget.emptyOrWhen(
  condition: () => list.isEmpty,
  emptyWidget: const EmptyStateWidget(),
)

Complete Page Example#

import 'package:core/core.dart';
import 'package:dependencies/dependencies.dart';

class MyPage extends HookWidget {
  const MyPage({super.key});

  @override
  Widget build(BuildContext context) {
    final appColors = context.appColors;

    return BlocSignalProvider(
      create: (_) => MyBloc(),
      child: BlocSignalBuilder<MyBloc, MyState>(
        builder: (context, state) {
          return Scaffold(
            headers: [
              AppBar(
                title: Text(
                  '페이지 제목',
                  style: context.textStyles.lgSemibold.copyWith(
                    color: appColors.neutral5,
                  ),
                ),
              ),
            ],
            child: Padding(
              padding: const EdgeInsets.symmetric(
                horizontal: CoreSpace.space16,
              ),
              child: Column(
                crossAxisAlignment: .start,
                children: [
                  const Gap.space16(),
                  Input(
                    type: CoreInputType.text,
                    placeholder: '이름을 입력하세요',
                    onChanged: (value) => context.read<MyBloc>().add(
                      MyEvent.nameChanged(value),
                    ),
                  ),
                  const Gap.space16(),
                  Button(
                    expanded: true,
                    enabled: state.isValid,
                    onPressed: () => context.read<MyBloc>().add(
                      const MyEvent.submitted(),
                    ),
                    child: const Text('저장'),
                  ),
                ],
              ),
            ).skeletonizer(enabled: state.isLoading),
          );
        },
      ),
    );
  }
}

Color Scheme (Console UI)#

AppColors Neutral Series#

// Header background (distinct from body)
color: context.appColors.neutral95,

// Dark border (clear separation)
border: Border(right: BorderSide(color: context.appColors.neutral70)),

// Default border
border: Border.all(color: context.appColors.neutral80),

ColorScheme Base Series#

OutlinedContainer(
  backgroundColor: theme.colorScheme.base100,
  borderColor: theme.colorScheme.base300,  // 진한 테두리
)

Reference Documents#

Refer to CLAUDE.md for the following:

• Color rules (AppColors, context.appColors)
• Dot Shorthand rules (Dart 3.10+) — note variant: .ghost, size: .sm
• BLoC Event/State patterns (sealed class)
• BLoC async handlers (isClosed check)
• Complete list of Context Extensions