Frame

Frame 은 CoUI 의 통합 레이아웃 프리미티브입니다. Flutter 의 Container / Row / Column / Wrap / Padding / Center / Align / SizedBox / Expanded / DecoratedBox / Opacity / Transform / ClipRRect / Visibility 와 Web 의 <div> 를 한 컴포넌트로 흡수하여, Figma Frame 의 모든 "Inspect" 슬롯이 1:1 로 코드 prop 에 대응합니다.

기본 사용법 (Basic Usage)#

// 단일 자식 + chrome
Frame(
  padding: CoreEdgeInsets.all(CoreSpace.space16),
  backgroundColor: theme.colorScheme.surface,
  borderRadius: CoreBorderRadius.all(CoreRadius.box),
  child: Text('Inside frame'),
)

// Auto Layout (Row)
Frame(
  direction: CoreFrameDirection.row,
  gap: CoreSpace.space12,
  crossAxisAlignment: CoreCrossAxisAlignment.center,
  children: [icon, label],
)

// Sizing + flex (이 frame 자체가 부모 flex 의 자식)
Frame(
  flex: 1,
  fit: CoreFlexFit.tight,
  child: child,
)

// 효과 (elevation + dashed border)
Frame(
  elevation: CoreFrameElevation.medium,
  borderColor: theme.colorScheme.outline,
  borderWidth: CoreBorderWidth.medium,
  borderStyle: CoreFrameBorderStyle.dashed,
  child: Text('Dashed elevated'),
)

// SEO 시맨틱 태그 (Web). Flutter 는 Semantics role 로 매핑.
Frame(
  tag: 'main',
  child: pageBody,
)

Live Preview#

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

  @override
  Component build(BuildContext context) {
    final cs = context.colorScheme;
    return Frame(
      direction: CoreFrameDirection.row,
      gap: CoreSpace.space12,
      crossAxisAlignment: CoreCrossAxisAlignment.center,
      padding: const CoreEdgeInsets.all(CoreSpace.space16),
      backgroundColor: 'rgb(var(--coui-${cs.surfaceContainer}))',
      borderRadius: const CoreBorderRadius.all(CoreRadius.radius16),
      borderColor: 'rgb(var(--coui-${cs.outlineVariant}))',
      borderWidth: CoreStrokeWidth.stroke1,
      children: [
        Icon(LucideIcons.frame, iconStyle: CoreIconStyle(size: CoreSpace.space24)),
        Text('Frame primitive'),
      ],
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    final colorScheme = Theme.of(context).colorScheme;
    return Frame(
      direction: CoreFrameDirection.row,
      gap: CoreSpace.space12,
      crossAxisAlignment: CoreCrossAxisAlignment.center,
      padding: const CoreEdgeInsets.all(CoreSpace.space16),
      backgroundColor: colorScheme.surfaceContainer.toValue(),
      borderRadius: const CoreBorderRadius.all(CoreRadius.radius16),
      borderColor: colorScheme.outlineVariant.toValue(),
      borderWidth: CoreStrokeWidth.stroke1,
      children: const [
        Icon(LucideIcons.frame, iconStyle: CoreIconStyle(size: CoreSpace.space24)),
        Text('Frame primitive'),
      ],
    );
  }
}

사용 시기 (When to Use)#

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

• Figma 디자인을 Flutter / Web 어느 쪽으로든 코드로 옮길 때 — 디자인의 한 Frame 이 그대로 한 Frame 으로 매핑됩니다.
• Auto Layout (direction · gap · alignment) 과 Sizing · Fill · Stroke · Effects 를 같이 다뤄야 할 때.
• 단순 <div> / Container 를 raw 위젯으로 박지 않고 디자인 토큰 경유로 통일하고 싶을 때.

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

• Scaffold: 흐름 레이아웃 한 영역 대신 헤더·푸터·사이드바를 가진 화면 셸이 필요할 때
• Card: 사용자 의미 있는 콘텐츠 슬롯·표면 단위가 필요할 때.
• Stacks / Position: 자식들이 z 축으로 겹치거나 절대 좌표로 배치돼야 할 때.

Props / Parameters#

W 는 Flutter의 Widget / Web의 Jaspr Component입니다. child / children은 같은 플랫폼 콘텐츠를 조립하는 슬롯입니다.

여기에는 위젯 생성자 파라미터만 적습니다. 시각 chrome 일부는 frameStyle (CoreFrameStyle) 슬롯으로도 흐릅니다 — 아래 레이어 표와 Style 표를 같이 보세요.

레이어 1 — 시각 / Figma#

레이어 2 — 동작#

레이어 3 — HTML / SEO (Web 우선, Flutter는 Semantics 매핑)#

레이어 4 — 접근성 / DOM 메타데이터#

자식#

스타일 시스템 (Style System)#

CoreFrameStyle 필드#

Figma 매핑#

동작 스펙 (Behavior)#

• visible이 거짓이면 콘텐츠를 렌더하지 않고 레이아웃에서 제거합니다. child와 children은 동시에 지정하지 않으며, direction에 따라 행·열·wrap 또는 단일 콘텐츠를 구성합니다.
• width / height / gap / blur 치수는 논리 px, opacity는 0~1 배율, flex는 grow 가중치입니다. 부모 제약과 자식의 flex 설정이 최종 레이아웃을 정합니다.
• onTap은 포인터 클릭·탭, onHover는 진입·이탈, onFocus는 포커스 변화를 알립니다. Frame이 버튼의 Enter/Space 활성화나 포커스 링을 자동 제공하지는 않습니다. 사용자 액션이면 Button / Clickable 을 합성합니다.

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

✅ Do#

Frame(
  borderColor: theme.colorScheme.outline,
  borderWidth: CoreStrokeWidth.stroke1,
  borderRadius: CoreBorderRadius.all(CoreRadius.radius8),
  child: content,
)

❌ Don't#

// ❌ child 와 children 동시 지정
Frame(
  child: Text('A'),
  children: [Text('A'), Text('B')],
)

✅ Do#

Frame(
  elevation: CoreFrameElevation.medium,
  child: content,
)

❌ Don't#

// ❌ boxShadow 가 있으면 elevation 은 조용히 무시됨
Frame(
  elevation: CoreFrameElevation.strong,
  boxShadow: CoreShadow.lg,
  child: content,
)

✅ Do#

Frame(
  direction: CoreFrameDirection.row,
  gap: CoreSpace.space8,
  children: [
    Icon(LucideIcons.house),
    Frame(flex: 1, child: Text('길어질 수 있는 라벨')),
  ],
)

빠른 오버라이드 (Chain)#

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

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        Frame(
          direction: CoreFrameDirection.row,
          gap: CoreSpace.space12,
          crossAxisAlignment: CoreCrossAxisAlignment.center,
          padding: const CoreEdgeInsets.all(CoreSpace.space16),
          children: const [
            Icon(
              LucideIcons.frame,
              iconStyle: CoreIconStyle(size: CoreSpace.space24),
            ),
            Text('Frame primitive'),
          ],
        ).radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderColor·borderWidth)까지 한 번에.
        Frame(
          direction: CoreFrameDirection.row,
          gap: CoreSpace.space12,
          crossAxisAlignment: CoreCrossAxisAlignment.center,
          padding: const CoreEdgeInsets.all(CoreSpace.space16),
          children: const [
            Icon(
              LucideIcons.frame,
              iconStyle: CoreIconStyle(size: CoreSpace.space24),
            ),
            Text('Full control'),
          ],
        ).withStyle(
          const CoreFrameStyle(
            backgroundColor: CoreColor.token(CoreColors.surfaceContainer),
            borderColor: CoreColor.token(CoreColors.tertiary),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
          ),
        ),
      ],
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return div(
      [
        // 토큰-정확 getter combo — 이름이 곧 값 (getter 이름 = Core 토큰 상수 1:1).
        Frame(
          direction: CoreFrameDirection.row,
          gap: CoreSpace.space12,
          crossAxisAlignment: CoreCrossAxisAlignment.center,
          padding: const CoreEdgeInsets.all(CoreSpace.space16),
          children: [
            Icon(
              LucideIcons.frame,
              iconStyle: CoreIconStyle(size: CoreSpace.space24),
            ),
            Text('Frame primitive'),
          ],
        ).radius16.primary,
        const Gap.space12(),
        // withStyle full-control — getter 가 없는 필드(borderColor·borderWidth)까지 한 번에.
        Frame(
          direction: CoreFrameDirection.row,
          gap: CoreSpace.space12,
          crossAxisAlignment: CoreCrossAxisAlignment.center,
          padding: const CoreEdgeInsets.all(CoreSpace.space16),
          children: [
            Icon(
              LucideIcons.frame,
              iconStyle: CoreIconStyle(size: CoreSpace.space24),
            ),
            Text('Full control'),
          ],
        ).withStyle(
          const CoreFrameStyle(
            backgroundColor: CoreColor.token(CoreColors.surfaceContainer),
            borderColor: CoreColor.token(CoreColors.tertiary),
            borderRadius: CoreBorderRadius.all(CoreRadius.radius24),
            borderWidth: CoreStrokeWidth.stroke2,
          ),
        ),
      ],
      classes: 'flex flex-col items-start',
    );
  }
}

접근성 (Accessibility)#

역할#

a11y 를 주지 않으면 역할 없는 컨테이너로 자식의 시맨틱을 통과시킵니다.

• Flutter: a11y 와 onTap 이 없으면 시맨틱 래핑도 없습니다. onTap 만 있으면 Semantics(button: true), a11y 를 주면 CoUISemantics 가 CoreSemanticRole 과 이름을 해석합니다. 명시한 역할은 버튼 역할로 덮이지 않습니다.
• Web: 루트는 tag(기본 div)이고 a11y.role / a11y.label 은 role / aria-label 로 나갑니다. a11y.attributes 는 caller attributes 뒤에 병합되어 같은 키를 덮습니다. dashed / dotted 보더의 장식 SVG 는 aria-hidden="true" 입니다.

a11y.id 와 a11y.attributes 는 Web 전용입니다. 랜드마크가 필요하면 CoreFrameA11y(role: CoreSemanticRole.navigation, label: 'Sidebar') 처럼 역할과 이름을 함께 주세요. Web 의 tag: 'nav' 만으로 Flutter 역할이 생기지는 않습니다.

키보드#

포커스 정지점과 키보드 활성화는 별개입니다. onTap 만 준 프레임은 Web 에서는 도달하지만 Flutter 에서는 도달하지 않습니다. 활성화할 표면에는 Button 을 쓰세요.

스크린 리더#

이름은 a11y.label 에서 옵니다. 생략하면 자식 콘텐츠가 읽힐 뿐 프레임 이름은 없습니다. status / alert 역할은 Flutter 의 live region 과 Web 의 해당 역할로 통보됩니다. CoUISemantics 는 역할의 전제 조건을 만족하지 못하면 역할을 떨어뜨립니다.

포커스 관리#

진입·이탈 시 포커스 이동도 트랩도 없습니다. 포커스 표시를 직접 그리지 않으므로 Flutter 의 Focus 는 시각 표시가 없고 Web 은 브라우저 기본 표시에 의존합니다.

알려진 제약#

• 클릭 가능한 프레임에 키보드 활성화가 없습니다. onTap 은 포인터 경로만 배선합니다. Web 은 호출부 이벤트로 보완할 수 있지만 공통 경로는 Button 입니다.
• tag 는 Web 전용입니다. Flutter 에서 같은 의미가 필요하면 a11y 도 채우세요.
• 랜드마크에는 이름을 주세요. Flutter 에서 .main / .navigation / .region / .contentInfo 는 이름이 없으면 역할이 emit 되지 않습니다.
• 상태를 전제로 하는 역할은 전용 컴포넌트를 쓰세요. Frame 은 selected / checked / value 를 CoUISemantics 에 넘기지 않아 .tab / .menuItemCheckbox / .menuItemRadio / .progressBar 의 전제 조건을 채우지 못합니다.
• 최소 히트 영역 보정이 없습니다. 렌더 크기가 히트 영역이므로 minWidth / minHeight 로 최소 크기를 확보하거나 전용 컨트롤을 쓰세요.

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

관련 컴포넌트 (Related Components)#

• Card: header / body / footer 슬롯이 있는 의미 단위 카드
• 스택 레이아웃: 자식이 z축으로 겹치거나 절대 좌표로 배치돼야 할 때