Card#

관련 정보를 하나의 단위로 묶어 표시하는 컨테이너입니다. media / header / body / footer / overlay 슬롯을 제공합니다.

Live Preview#

class CardDefaultExample extends StatelessComponent {
  const CardDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return Card(
      header: Text('Card Title'),
      body: Text('This is the card body content.'),
      footer: Button(
        variant: CoreButtonVariant.primary,
        onPressed: () {},
        child: Text('Action'),
      ),
    );
  }
}

class CardDefaultExample extends StatelessWidget {
  const CardDefaultExample({super.key});

  @override
  Widget build(BuildContext context) {
    return Card(
      header: const Text('Card Title'),
      body: const Text('This is the card body content.'),
      footer: Button(
        variant: CoreButtonVariant.primary,
        onPressed: () {},
        child: const Text('Action'),
      ),
    );
  }
}

class CardFilledExample extends StatelessComponent {
  const CardFilledExample({super.key});

  @override
  Component build(BuildContext context) {
    return Card(
      variant: CoreCardVariant.filled,
      header: Text('Filled Card'),
      body: Text('Filled variant with surface container background.'),
    );
  }
}

class CardFilledExample extends StatelessWidget {
  const CardFilledExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const Card(
      variant: CoreCardVariant.filled,
      header: Text('Filled Card'),
      body: Text('Filled variant with surface container background.'),
    );
  }
}

class CardElevatedExample extends StatelessComponent {
  const CardElevatedExample({super.key});

  @override
  Component build(BuildContext context) {
    return Card(
      elevation: CoreCardElevation.medium,
      header: Text('Elevated Card'),
      body: Text('Card with medium shadow elevation.'),
    );
  }
}

class CardElevatedExample extends StatelessWidget {
  const CardElevatedExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const Card(
      elevation: CoreCardElevation.medium,
      header: Text('Elevated Card'),
      body: Text('Card with medium shadow elevation.'),
    );
  }
}

class CardChainExample extends StatelessComponent {
  const CardChainExample({super.key});

  @override
  Component build(BuildContext context) {
    return div(
      [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        Card(
          header: Text('Card Title'),
          body: Text('This is the card body content.'),
          footer: Button(
            variant: CoreButtonVariant.primary,
            onPressed: () {},
            child: Text('Action'),
          ),
        ).radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderWidth/padding)까지.
        Card(
          header: Text('Card Title'),
          body: Text('This is the card body content.'),
          footer: Button(
            variant: CoreButtonVariant.primary,
            onPressed: () {},
            child: Text('Action'),
          ),
        ).withStyle(
          const CoreCardStyle(
            padding: CoreEdgeInsets.all(CoreSpace.space24),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
            backgroundColor: CoreColor.token(
              CoreColors.surfaceContainerHighest,
            ),
            borderColor: CoreColor.token(CoreColors.tertiary),
          ),
        ),
      ],
      classes: 'flex flex-col items-start',
    );
  }
}

class CardChainExample extends StatelessWidget {
  const CardChainExample({super.key});

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        Card(
          header: const Text('Card Title'),
          body: const Text('This is the card body content.'),
          footer: Button(
            variant: CoreButtonVariant.primary,
            onPressed: () {},
            child: const Text('Action'),
          ),
        ).radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderWidth/padding)까지.
        Card(
          header: const Text('Card Title'),
          body: const Text('This is the card body content.'),
          footer: Button(
            variant: CoreButtonVariant.primary,
            onPressed: () {},
            child: const Text('Action'),
          ),
        ).withStyle(
          const CoreCardStyle(
            padding: CoreEdgeInsets.all(CoreSpace.space24),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
            backgroundColor: CoreColor.token(
              CoreColors.surfaceContainerHighest,
            ),
            borderColor: CoreColor.token(CoreColors.tertiary),
          ),
        ),
      ],
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 관련 정보를 하나의 단위로 묶어 표시할 때 (프로필, 상품, 게시물 등)
• 시각적으로 콘텐츠를 구분하고 계층을 만들 때
• 클릭 가능한 콘텐츠 블록이 필요할 때

대신 다른 컴포넌트를 사용하세요:

• Accordion: 접고 펼 수 있는 콘텐츠 섹션이 필요할 때
• Table: 구조화된 데이터를 행과 열로 표시할 때
• Dialog: 임시 콘텐츠를 모달로 표시할 때

기본 사용법 (Basic Usage)#

// 기본 카드 (outlined, no elevation)
Card(
  body: Text('카드 내용'),
)

// 슬롯 기반 레이아웃
Card(
  header: Text('제목'),
  body: Text('본문 내용입니다.'),
  footer: Text('푸터'),
)

// variant + elevation (chrome / dimensional 은 cardStyle 로 통합)
Card(
  variant: CoreCardVariant.filled,
  cardStyle: CoreCardStyle(
    elevation: CoreCardElevation.medium,
  ),
  body: Text('강조된 카드'),
)

// 클릭 가능
Card(
  onTap: () => print('clicked'),
  body: Text('눌러 보세요'),
)

Props / Parameters#

CoreCardStyle 필드#

CoreCardStyle 변형별 기본값 (CoreCardVariantStyle)#

빠른 오버라이드 (Chain)#

이미 만든 Card 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다. .radius4처럼 Core 토큰 상수 이름과 똑같은 이름의 getter도 있습니다 — withStyle을 한 번 더 줄인 sugar로, 이름이 곧 값이라(radius4 == CoreRadius.radius4) 어느 컴포넌트에서 써도 뜻이 갈리지 않습니다.

class CardChainExample extends StatelessWidget {
  const CardChainExample({super.key});

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        Card(
          header: const Text('Card Title'),
          body: const Text('This is the card body content.'),
          footer: Button(
            variant: CoreButtonVariant.primary,
            onPressed: () {},
            child: const Text('Action'),
          ),
        ).radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderWidth/padding)까지.
        Card(
          header: const Text('Card Title'),
          body: const Text('This is the card body content.'),
          footer: Button(
            variant: CoreButtonVariant.primary,
            onPressed: () {},
            child: const Text('Action'),
          ),
        ).withStyle(
          const CoreCardStyle(
            padding: CoreEdgeInsets.all(CoreSpace.space24),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
            backgroundColor: CoreColor.token(
              CoreColors.surfaceContainerHighest,
            ),
            borderColor: CoreColor.token(CoreColors.tertiary),
          ),
        ),
      ],
    );
  }
}

class CardChainExample extends StatelessComponent {
  const CardChainExample({super.key});

  @override
  Component build(BuildContext context) {
    return div(
      [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        Card(
          header: Text('Card Title'),
          body: Text('This is the card body content.'),
          footer: Button(
            variant: CoreButtonVariant.primary,
            onPressed: () {},
            child: Text('Action'),
          ),
        ).radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderWidth/padding)까지.
        Card(
          header: Text('Card Title'),
          body: Text('This is the card body content.'),
          footer: Button(
            variant: CoreButtonVariant.primary,
            onPressed: () {},
            child: Text('Action'),
          ),
        ).withStyle(
          const CoreCardStyle(
            padding: CoreEdgeInsets.all(CoreSpace.space24),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
            backgroundColor: CoreColor.token(
              CoreColors.surfaceContainerHighest,
            ),
            borderColor: CoreColor.token(CoreColors.tertiary),
          ),
        ),
      ],
      classes: 'flex flex-col items-start',
    );
  }
}

스타일 시스템 — cardStyle#

Card 의 모든 chrome / dimensional 오버라이드는 단일 cardStyle 필드(CoreCardStyle) 하나로 흐릅니다. width / padding / boxShadow / elevation 같은 값은 모두 CoreCardStyle 안의 nullable 필드이며, 위젯 생성자에는 chrome 파라미터가 없습니다.

Card(
  variant: CoreCardVariant.outlined,
  cardStyle: CoreCardStyle(
    padding: CoreEdgeInsets.all(CoreSpace.space24),
    borderRadius: CoreBorderRadius.all(CoreRadius.radius12),
    backgroundColor: CoreColor.token(CoreColors.surfaceContainer),
    elevation: CoreCardElevation.soft,
    sizing: CoreCardSizing.fixed,
    width: 320,
  ),
  header: Text('제목'),
  body: Text('본문'),
)

Resolve chain#

cardStyle 은 다음 체인을 거쳐 최종 값으로 해석됩니다 (오른쪽이 이김):

design system default
  → CoreCardTheme.style                        // 프로젝트 공통
  → CoreCardTheme.variantStyles[variant]       // variant 별 오버라이드
  → parent component slot override             // 예: TimePicker.popoverPanelStyle
  → widget.cardStyle                           // 인스턴스별 오버라이드

각 레이어는 CoreCardStyle 의 어떤 필드든 부분적으로 채울 수 있습니다. null 인 필드는 다음 레이어로 넘겨주고, non-null 인 필드는 해당 레이어에서 확정됩니다.

테마 적용#

ThemeData.fromCore(
  coreComponentTheme: CoreComponentTheme(
    card: CoreCardTheme(
      style: CoreCardStyle(
        // 모든 카드에 적용되는 기본
        borderRadius: CoreBorderRadius.all(CoreRadius.radius16),
        padding: CoreEdgeInsets.all(CoreSpace.space20),
      ),
      variantStyles: {
        CoreCardVariant.filled: CoreCardStyle(
          backgroundColor: CoreColor.token(CoreColors.primaryContainer),
        ),
      },
    ),
  ),
)

변형 (Variants)#

Outlined (기본)#

Card(
  variant: CoreCardVariant.outlined,
  body: Text('외곽선만'),
)

Filled#

Card(
  variant: CoreCardVariant.filled,
  body: Text('배경색 채움'),
)

Elevation 단계#

Card(
  cardStyle: CoreCardStyle(elevation: CoreCardElevation.none),
  body: Text('평면'),
)
Card(
  cardStyle: CoreCardStyle(elevation: CoreCardElevation.soft),
  body: Text('약한 그림자'),
)
Card(
  cardStyle: CoreCardStyle(elevation: CoreCardElevation.medium),
  body: Text('중간 그림자'),
)
Card(
  cardStyle: CoreCardStyle(elevation: CoreCardElevation.strong),
  body: Text('강한 그림자'),
)

미디어 카드 (이미지 + 콘텐츠)#

Card(
  media: Image.network('https://example.com/photo.jpg'),
  header: Text('상품명'),
  body: Text('상품 설명'),
  footer: Text('가격'),
)

동작 스펙 (Behavior)#

인터랙션#

• 탭/클릭: onTap 설정 시 전체 카드 영역 클릭 가능
• 호버 (onTap 있을 때): 커서가 pointer 로 변경 + hover shadow 애니메이션

애니메이션#

• chrome (배경/보더/반경/패딩) 전환: cardStyle.chromeAnimationDuration (기본 CoreDuration.normal = 200ms)
• hover shadow 전환: cardStyle.hoverShadowAnimationDuration (기본 CoreDuration.normal = 200ms)

사용 가이드라인 (Usage Guidelines)#

✅ Do#

Card(
  cardStyle: CoreCardStyle(
    sizing: CoreCardSizing.fixed,
    width: 320,
    height: 200,
  ),
  body: Text('고정 크기 카드'),
)

❌ Don't#

// ❌ body 안의 버튼에만 onTap — 카드 전체 클릭 영역을 놓침
Card(
  body: GestureDetector(onTap: handleTap, child: Text('상세보기')),
)

// ✅ Card 자체의 onTap 사용 — 전체 영역 + hover shadow + cursor 파리티까지 포함
Card(
  onTap: handleTap,
  body: Text('상세보기'),
)

접근성 (Accessibility)#

시맨틱#

• Flutter: 기본은 Container. onTap이 있으면 MouseRegion + GestureDetector로 감쌉니다.
• Web: 기본은 <div>. onTap이 있으면 role="button", tabindex="0"을 붙입니다.

키보드#

• onTap을 주면 Enter / Space로 카드를 활성화할 수 있습니다.

크로스 플랫폼 차이점 (Platform Differences)#

관련 컴포넌트 (Related Components)#

• Accordion: 접고 펼 수 있는 섹션
• Badge: Card 안에 상태 표시