Mockup#

콘텐츠를 실제 디바이스나 앱 화면처럼 감싸는 목업 프레임 컴포넌트입니다. 문서, 랜딩 페이지, 스크린샷 등 시각적 프레젠테이션에 활용됩니다.

Live Preview#

class MockupPhoneExample extends StatefulComponent {
  const MockupPhoneExample({super.key});

  @override
  State<MockupPhoneExample> createState() => _MockupPhoneExampleState();
}

class _MockupPhoneExampleState extends State<MockupPhoneExample> {
  @override
  Component build(BuildContext context) {
    return MockupPhone(
      child: Text('App Screen').bodyMedium.onSurface,
    );
  }
}

class MockupPhoneExample extends StatefulWidget {
  const MockupPhoneExample({super.key});

  @override
  State<MockupPhoneExample> createState() => _MockupPhoneExampleState();
}

class _MockupPhoneExampleState extends State<MockupPhoneExample> {
  @override
  Widget build(BuildContext context) {
    return MockupPhone(
      child: Text('App Screen').bodyMedium.onSurface,
    );
  }
}

class MockupBrowserExample extends StatefulComponent {
  const MockupBrowserExample({super.key});

  @override
  State<MockupBrowserExample> createState() => _MockupBrowserExampleState();
}

class _MockupBrowserExampleState extends State<MockupBrowserExample> {
  @override
  Component build(BuildContext context) {
    return MockupBrowser(
      addressBar: 'https://coui.dev',
      child: Text('Page content').bodyMedium.onSurface,
    );
  }
}

class MockupBrowserExample extends StatefulWidget {
  const MockupBrowserExample({super.key});

  @override
  State<MockupBrowserExample> createState() => _MockupBrowserExampleState();
}

class _MockupBrowserExampleState extends State<MockupBrowserExample> {
  @override
  Widget build(BuildContext context) {
    return MockupBrowser(
      addressBar: 'https://coui.dev',
      child: Text('Page content').bodyMedium.onSurface,
    );
  }
}

class MockupCodeExample extends StatefulComponent {
  const MockupCodeExample({super.key});

  @override
  State<MockupCodeExample> createState() => _MockupCodeExampleState();
}

class _MockupCodeExampleState extends State<MockupCodeExample> {
  @override
  Component build(BuildContext context) {
    return MockupCode.fromString(
      "void main() {\n  print('Hello!');\n}",
      showLineNumbers: true,
    );
  }
}

class MockupCodeExample extends StatefulWidget {
  const MockupCodeExample({super.key});

  @override
  State<MockupCodeExample> createState() => _MockupCodeExampleState();
}

class _MockupCodeExampleState extends State<MockupCodeExample> {
  @override
  Widget build(BuildContext context) {
    return MockupCode.fromString(
      "void main() {\n  print('Hello!');\n}",
    );
  }
}

class MockupWindowExample extends StatefulComponent {
  const MockupWindowExample({super.key});

  @override
  State<MockupWindowExample> createState() => _MockupWindowExampleState();
}

class _MockupWindowExampleState extends State<MockupWindowExample> {
  @override
  Component build(BuildContext context) {
    return MockupWindow(
      child: Text('Window content').bodyMedium.onSurface,
    );
  }
}

class MockupWindowExample extends StatefulWidget {
  const MockupWindowExample({super.key});

  @override
  State<MockupWindowExample> createState() => _MockupWindowExampleState();
}

class _MockupWindowExampleState extends State<MockupWindowExample> {
  @override
  Widget build(BuildContext context) {
    return MockupWindow(
      child: Text('Window content').bodyMedium.onSurface,
    );
  }
}

class MockupChainExample extends StatefulComponent {
  const MockupChainExample({super.key});

  @override
  State<MockupChainExample> createState() => _MockupChainExampleState();
}

class _MockupChainExampleState extends State<MockupChainExample> {
  @override
  Component build(BuildContext context) {
    return MockupBrowser(
      addressBar: 'https://coui.dev',
      child: Text('Page content'),
    ).radius8.primary;
  }
}

class MockupChainExample extends StatefulWidget {
  const MockupChainExample({super.key});

  @override
  State<MockupChainExample> createState() => _MockupChainExampleState();
}

class _MockupChainExampleState extends State<MockupChainExample> {
  @override
  Widget build(BuildContext context) {
    return MockupBrowser(
      addressBar: 'https://dev',
      child: const Text('Page content'),
    ).radius8.primary;
  }
}

사용 시기 (When to Use)#

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

• 랜딩 페이지에서 앱/웹 화면을 디바이스 프레임 안에 표시할 때
• 기술 문서에서 코드 예제를 코드 에디터 스타일로 표시할 때
• 데모나 쇼케이스에서 스크린샷을 실제 기기처럼 보여줄 때

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

• Card: 단순한 콘텐츠 카드 레이아웃에
• CodeSnippet: 코드 하이라이팅이 필요한 코드 블록에

기본 사용법 (Basic Usage)#

// 브라우저 목업
MockupBrowser(
  addressBar: 'https://coui.cocode.im',
  child: Image.asset('assets/screenshots/dashboard.png'),
)

// 폰 목업
MockupPhone(
  child: Image.asset('assets/screenshots/app_home.png'),
)

// 코드 에디터 목업
MockupCode.fromString('void main() {\n  runApp(const MyApp());\n}')

// 윈도우 목업
MockupWindow(
  child: Text('윈도우 내용'),
)

// 브라우저 목업
MockupBrowser(
  addressBar: 'https://coui.cocode.im',
  child: img(src: 'screenshot.png', alt: 'CoUI 디자인 시스템'),
)

// 폰 목업
MockupPhone(
  child: img(src: 'app-screenshot.png', alt: '앱 화면'),
)

// 코드 목업 (fromString 팩토리 생성자)
MockupCode.fromString(
  'npm i coui\ninstalling...\nDone!',
  showLineNumbers: true,
)

// 윈도우 목업
MockupWindow(
  child: Text('윈도우 내용'),
)

빠른 오버라이드 (Chain)#

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

MockupBrowser(
  addressBar: 'https://coui.dev',
  child: Text('Page content').bodyMedium.onSurface,
).radius8.primary

MockupBrowser(
  addressBar: 'https://coui.dev',
  child: Text('Page content').bodyMedium.onSurface,
).radius8.primary

Props / Parameters#

각 목업은 별도의 통일 컴포넌트 (MockupBrowser / MockupPhone / MockupCode / MockupWindow) 로 제공됩니다. chrome / colour / border-radius override 는 모두 각 컴포넌트의 단일 *Style 슬롯으로 흐릅니다.

MockupBrowser#

MockupPhone#

MockupCode#

MockupWindow#

스타일 시스템 (Style System)#

네 목업 컴포넌트는 각자 전용 Style 슬롯을 갖습니다. CoreMockupTheme.style (CoreMockupStyle)은 네 목업이 공유하는 cross-variant chrome이며, 컴포넌트별 Theme 보다 먼저 merge chain 에 들어갑니다.

CoreMockupStyle 필드#

CoreMockupBrowserStyle#

CoreMockupPhoneStyle#

CoreMockupCodeStyle#

CoreMockupWindowStyle#

Resolve chain#

Core{Variant}Style.defaultX                                  // 디자인 시스템 기본값
  → CoreMockupTheme.style                                    // 네 목업 공유 chrome
  → CoreMockup{Variant}Theme.style                           // 프로젝트 공통
  → widget.mockup{Variant}Style                              // 인스턴스별

변형 (Variants)#

Browser#

주소창이 있는 브라우저 프레임입니다.

MockupBrowser(
  addressBar: 'https://example.com/dashboard',
  child: DashboardScreenshot(),
)

Phone#

모바일 기기 외형(카메라 노치 등)을 갖춘 스마트폰 프레임입니다.

MockupPhone(
  child: MobileAppPreview(),
)

Code#

코드 에디터 스타일의 프레임입니다. 선택적으로 줄 번호가 표시됩니다.

MockupCode.fromString(
  'print("Hello, World!");',
  showLineNumbers: true,
)

Window#

데스크탑 앱 윈도우 스타일의 프레임입니다. 트래픽라이트 컨트롤이 포함됩니다.

MockupWindow(
  child: AppContent(),
)

동작 스펙 (Behavior)#

인터랙션#

• 기본적으로 정적 프레임으로 인터랙션 없음
• child에 인터랙션 가능한 위젯을 넣으면 프레임 안에서 동작

상태 전환#

• 정적 컴포넌트로 별도 상태 전환 없음

애니메이션#

• 별도 애니메이션 없음 (자식 위젯의 애니메이션은 그대로 동작)

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

✅ Do#

MockupPhone(
  child: Image.asset(
    'assets/screenshots/app_home.png',
    fit: BoxFit.cover,
  ),
)

❌ Don't#

// ❌ 성능 문제 야기할 수 있음
MockupPhone(
  child: MaterialApp(
    home: ComplexAppWithManyAnimations(),
  ),
)

✅ Do#

MockupCode.fromString(
  "Button(\n  onPressed: handlePressed,\n  child: const Text('클릭'),\n)",
)

❌ Don't#

// ❌ 실제 앱 UI에 Phone 목업 사용
Scaffold(
  body: MockupPhone( // 실제 앱인데 Phone 프레임?
    child: actualAppContent,
  ),
)

✅ Do#

MockupPhone(
  child: AppScreenPreview(
    // 실제 앱 화면과 유사한 내용
    content: RealisticDemoContent(),
  ),
)

❌ Don't#

// ❌ 실제 앱에서 Mockup을 레이아웃으로 사용
Scaffold(
  body: MockupBrowser(
    addressBar: 'https://example.com',
    child: actualAppContent,  // 실제 콘텐츠
  ),
)

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: Semantics(label: '브라우저 목업: CoUI 문서') 형태로 프레임 설명 추가 권장
• Web: 프레임에 role / aria-* 를 붙이지 않습니다 — 순수 <div> 래퍼이므로 스크린 리더에는 내부 콘텐츠만 노출됩니다. 프레임 자체를 설명해야 하면 호출자가 attributes 로 aria-label 을 넘기세요.

터치 타겟#

• 목업 프레임 자체는 터치 타겟 없음
• 내부 인터랙션 요소는 자식 위젯의 타겟 크기를 따름

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

어느 플랫폼도 CustomPaint / CustomPainter 를 쓰지 않습니다 — 네 목업 모두 박스 decoration 으로 프레임을 그립니다. MockupCode 는 보더가 없습니다 (CoreMockupCodeStyle 에 borderColor 필드 자체가 없음) — 배경색과 radius 만으로 프레임을 만듭니다. Web 역시 box-shadow 를 쓰지 않습니다.

관련 컴포넌트 (Related Components)#

• Card: 단순한 콘텐츠 컨테이너가 필요할 때 사용
• CodeSnippet: 코드 하이라이팅이 필요한 코드 블록에 사용

조합 예제#

// 랜딩 페이지 히어로 섹션
Row(
  children: [
    Expanded(
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text('CoUI로 아름다운 UI 만들기').headlineLarge.onSurface,
          const Gap.space16(),
          Text('Flutter와 Web을 동시에 지원하는 디자인 시스템').bodyMedium.onSurfaceVariant,
          const Gap.space24(),
          Button(
            onPressed: handleGetStarted,
            child: const Text('시작하기'),
          ),
        ],
      ),
    ),
    const Gap.space32(),
    Expanded(
      child: MockupBrowser(
        addressBar: 'https://coui.cocode.im',
        child: Image.asset('assets/screenshots/landing.png'),
      ),
    ),
  ],
)