Claude Code Flexbox 실전 레이아웃 패턴

Flexbox는 한 방향 UI를 안정시키는 도구입니다

Flexbox는 CSS에서 요소를 한 방향으로 배치하는 레이아웃 모델입니다. 한 줄의 가로 배치나 한 열의 세로 배치를 다룰 때 강합니다. 실제 UI에서는 내비게이션, 버튼 묶음, 카드 목록, 검색 바, 이메일 폼, 툴바, 글 하단 CTA가 대표적인 대상입니다. 행과 열을 동시에 엄격하게 제어해야 하는 상품 그리드나 대시보드는 CSS Grid가 더 나을 수 있지만, 한 줄의 UI가 정렬되고 줄바꿈되며 좁은 화면에서도 버티게 하려면 Flexbox가 가장 빠른 선택입니다.

Claude Code는 Flexbox 코드를 빠르게 만들 수 있지만, 프롬프트가 모호하면 결과도 모호합니다. “반응형으로 만들어 줘”라고만 쓰면 데스크톱에서는 좋아 보여도 360px 화면에서 가로 스크롤이 생기거나, 긴 제목이 카드를 밀어내거나, 상담 버튼이 두 줄로 깨질 수 있습니다. 번역된 문장, 긴 URL, 이메일 주소, 제품 CTA가 들어간 실제 화면을 기준으로 요청해야 합니다.

이 글은 Claude Code에 Flexbox를 맡길 때 필요한 용어, 재사용 가능한 프롬프트, 네 가지 Use case, 자주 보는 Pitfall, 복사해서 실행할 수 있는 HTML/CSS, 검수 체크리스트를 정리합니다. 더 넓은 화면 설계는 Claude Code 반응형 디자인, 시각 규칙은 디자인 시스템 구현, 키보드와 읽기 흐름은 접근성 구현도 함께 확인하세요.

공식 기준은 MDN의 Flexbox 기본 개념, flex 속성, gap 속성, 그리고 CSS Flexible Box Layout Module Level 1입니다. Claude Code의 출력이 낯선 축약 속성을 사용할 때, 이 문서들을 기준으로 리뷰하면 판단이 선명해집니다.

flowchart LR
  A["실제 UI 요구"] --> B["Flex container"]
  B --> C["main axis 주축"]
  B --> D["cross axis 교차축"]
  C --> E["gap / flex / wrap"]
  D --> F["align-items / min-width"]
  E --> G["내비게이션, 카드, 폼, CTA"]
  F --> G

초보자가 먼저 알아야 할 용어

display: flex가 붙은 부모는 flex container이고, 그 바로 아래 자식은 flex item입니다. 주축은 아이템이 흐르는 방향입니다. flex-direction: row면 가로, column이면 세로입니다. 교차축은 주축과 수직인 방향입니다. justify-content는 주축의 분배를, align-items는 교차축의 정렬을 제어합니다.

gap은 아이템 사이의 간격입니다. 각 자식에 margin-right를 붙이는 방식보다 부모가 간격을 관리하는 쪽이 읽기 쉽고, 줄바꿈이 생겨도 마지막 아이템 주변에 이상한 여백이 남지 않습니다. flex-wrap: wrap은 공간이 부족할 때 다음 줄로 넘기는 규칙입니다. 모바일에서 가로 스크롤을 피하려면 거의 항상 검토해야 합니다.

flex: 1 1 220px는 flex-grow, flex-shrink, flex-basis를 합친 축약입니다. 220px을 기준으로 시작하고, 여유가 있으면 커지고, 부족하면 줄어듭니다. 카드와 입력창에는 유용하지만 로고, 아이콘, 짧은 버튼에는 과합니다. 그런 요소는 flex: 0 0 auto로 내용 너비를 지키는 편이 안전합니다.

min-width: 0도 중요합니다. Flex item은 기본적으로 콘텐츠보다 작게 줄어들지 않는 경우가 있습니다. 긴 영어 제목, URL, 이메일 주소, 코드명이 들어오면 카드가 부모 너비를 밀어내고 페이지 전체에 가로 스크롤이 생길 수 있습니다. 카드에 min-width: 0, 텍스트에 overflow-wrap: anywhere를 넣으면 이 문제를 줄일 수 있습니다.

Claude Code에 줄 프롬프트

다음처럼 범위, 줄바꿈, CTA, 검수 폭을 함께 요청합니다.

Flexbox로 반응형 내비게이션, 카드 목록, 가입 폼, 글 하단 CTA를 구현해 주세요.
기존 class 명명 방식과 주요 CTA 링크는 유지해 주세요.
데스크톱은 가로 배치, 720px 이하는 필요한 곳만 세로로 쌓아 주세요.
간격은 gap으로 관리하고, 링크 그룹과 CTA 그룹은 별도 flex container로 나누어 주세요.
긴 제목, URL, 이메일이 넘치지 않도록 min-width: 0과 overflow-wrap을 넣어 주세요.
복사해서 실행 가능한 HTML/CSS를 반환하고 360px, 720px, 1024px에서 가로 스크롤을 확인해 주세요.

“필요한 곳만”이라는 조건이 중요합니다. 모바일이라고 모든 요소를 세로로 쌓으면 헤더가 너무 길어지고 CTA의 우선순위가 흐려집니다. 브랜드는 유지하고 링크 그룹만 줄바꿈할지, CTA 버튼은 언제 전체 폭으로 바꿀지 명시해야 Claude Code의 결과를 검수하기 쉽습니다.

Use case 1: 반응형 내비게이션

내비게이션은 대표적인 Use case입니다. 브랜드, 링크, CTA가 모두 한 줄에 있지만 동작 규칙은 다릅니다. 브랜드는 줄어들면 안 되고, 링크는 줄바꿈이 가능하며, CTA는 터치 가능한 높이를 유지해야 합니다. 바깥 컨테이너 하나에 justify-content: space-between만 넣으면 링크가 늘거나 번역 문장이 길어질 때 간격이 쉽게 깨집니다.

더 안전한 패턴은 중첩 Flexbox입니다. 헤더 자체가 flex container가 되고, 링크 묶음도 별도의 flex container가 됩니다. CTA는 내용 너비를 보존하는 item으로 둡니다. 이렇게 나누면 Claude Code에 “링크 그룹만 wrap 가능”, “CTA는 줄어들지 않게”라고 지시할 수 있습니다.

ClaudeCodeLab에서는 독자가 Claude Code 제품으로 이동하거나 교육 및 상담을 예약합니다. 모바일에서 이 CTA가 보이지 않으면 글은 읽혀도 전환 경로가 끊깁니다. 내비게이션은 장식이 아니라 수익 경로의 일부로 검수해야 합니다.

Use case 2: 글, 가격, 기능 카드

카드 목록도 Flexbox가 잘 맞는 Use case입니다. 글 카드, 가격 플랜, 기능 요약, 고객 사례처럼 2개에서 4개 정도의 카드라면 flex: 1 1 220px로 충분히 안정적인 줄바꿈을 만들 수 있습니다. 각 카드는 220px을 기준으로 시작하고, 공간이 있으면 넓어지고, 부족하면 다음 줄로 이동합니다.

엄격한 행과 열이 필요한 상품 카탈로그라면 CSS Grid가 낫습니다. 하지만 “카드 몇 개를 한 줄에 놓고 좁으면 자연스럽게 줄바꿈”이 목표라면 Flexbox가 더 읽기 쉽고 Claude Code가 수정하기도 쉽습니다.

검수할 때는 짧은 더미 텍스트만 쓰면 안 됩니다. 긴 영문 제품명, 한국어와 영어가 섞인 제목, URL 같은 문자열을 카드에 넣어 보세요. 카드에 min-width: 0이 없으면 긴 문자열이 화면 밖으로 밀릴 수 있습니다.

Use case 3: 가입 폼과 검색 바

폼은 라벨, 입력창, 버튼처럼 성격이 다른 요소가 함께 있기 때문에 Flexbox와 잘 맞습니다. 데스크톱에서는 한 줄로 빠르게 입력하게 하고, 모바일에서는 읽기 쉬운 폭으로 세로 배치합니다. 이메일 가입, 자료 다운로드, 검색, 쿠폰 입력처럼 짧은 폼일수록 깨진 레이아웃이 더 눈에 띕니다.

입력창은 flex: 1 1 16rem, 버튼은 flex: 0 0 auto가 좋은 기본값입니다. 입력창은 남는 공간을 쓰고 줄어들 수 있지만, 버튼은 내용 너비와 터치 높이를 지킵니다. 폼에 flex-wrap: wrap을 넣으면 좁은 화면에서 버튼이 다음 줄로 자연스럽게 내려갑니다.

또한 Claude Code가 의미 있는 HTML을 유지해야 합니다. label의 for와 input의 id를 맞추고, 이메일은 type="email", 필수 입력은 required를 사용합니다. 포커스 스타일을 지우지 않는 것도 중요합니다.

Use case 4: 글 하단 CTA

글 하단 CTA는 설명문과 버튼 묶음으로 구성됩니다. 텍스트 블록은 가능한 공간을 쓰고, 버튼 묶음은 내부에서 줄바꿈할 수 있게 하면 안정적입니다. 독자가 바로 쓸 템플릿을 찾는다면 products로, 팀 도입과 리뷰 규칙이 필요하다면 training으로 안내할 수 있습니다.

기술 글의 끝에서는 광고처럼 큰 중앙 정렬 블록보다 조용하고 명확한 다음 행동이 좋습니다. 설명은 먼저 읽히고, 버튼은 그다음에 보이며, 모바일에서는 같은 순서로 세로 배치되는 구조가 자연스럽습니다.

복사해서 쓰는 HTML

<main class="flex-demo">
  <nav class="site-nav" aria-label="Primary">
    <a class="site-nav__brand" href="/ko/">ClaudeCodeLab</a>
    <div class="site-nav__links">
      <a href="/ko/blog/claude-code-responsive-design/">Responsive</a>
      <a href="/ko/blog/claude-code-design-system/">Design System</a>
      <a href="/ko/blog/claude-code-accessibility/">Accessibility</a>
    </div>
    <a class="site-nav__cta" href="/ko/training/">상담 예약</a>
  </nav>

  <section class="card-row" aria-label="Use cases">
    <article class="feature-card">
      <h2>Navigation</h2>
      <p>브랜드는 유지하고 링크는 줄바꿈하며 CTA는 누르기 쉬운 크기를 지킵니다.</p>
      <a href="/ko/blog/claude-code-responsive-design/">가이드 보기</a>
    </article>
    <article class="feature-card">
      <h2>Cards</h2>
      <p>카드는 기준 폭에서 시작해 늘어나고, 긴 문장도 카드 안에서 줄바꿈합니다.</p>
      <a href="/ko/products/">제품 보기</a>
    </article>
    <article class="feature-card">
      <h2>Forms</h2>
      <p>입력창은 남는 공간을 쓰고 버튼은 모바일에서도 누르기 쉽게 유지합니다.</p>
      <a href="/ko/training/">도움 받기</a>
    </article>
  </section>

  <form class="signup-form" action="/ko/thanks/" method="post">
    <label for="email">무료 체크리스트 받기</label>
    <input id="email" name="email" type="email" placeholder="you@example.com" required />
    <button type="submit">다운로드</button>
  </form>
</main>

복사해서 쓰는 CSS

* {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  color: #172026;
  background: #f6f8fb;
}

.flex-demo {
  width: min(1120px, calc(100% - 32px));
  margin: 0 auto;
  padding: 24px 0 48px;
}

.site-nav,
.site-nav__links,
.card-row,
.signup-form {
  display: flex;
  gap: 16px;
}

.site-nav {
  align-items: center;
  justify-content: space-between;
  flex-wrap: wrap;
}

.site-nav__brand,
.site-nav__cta,
.signup-form button {
  flex: 0 0 auto;
}

.site-nav__links {
  flex: 1 1 420px;
  justify-content: center;
  flex-wrap: wrap;
  min-width: 0;
}

.card-row {
  flex-wrap: wrap;
}

.feature-card {
  flex: 1 1 220px;
  min-width: 0;
  padding: 20px;
  border: 1px solid #d9e2ec;
  border-radius: 8px;
  background: #fff;
}

.feature-card p {
  overflow-wrap: anywhere;
}

.signup-form {
  align-items: end;
  flex-wrap: wrap;
  padding: 20px;
  border-radius: 8px;
  background: #e8f5f3;
}

.signup-form label {
  flex: 1 1 180px;
  font-weight: 700;
}

.signup-form input {
  flex: 1 1 16rem;
  min-width: 12rem;
  min-height: 44px;
}

.signup-form button,
.site-nav__cta {
  min-height: 44px;
  border: 0;
  border-radius: 8px;
  padding: 0 14px;
  color: #fff;
  background: #0f766e;
  font-weight: 700;
}

@media (max-width: 720px) {
  .site-nav,
  .signup-form {
    align-items: stretch;
  }

  .site-nav__links {
    justify-content: flex-start;
  }

  .site-nav__cta,
  .signup-form button {
    width: 100%;
  }
}

Pitfall과 검수 방법

첫 번째 Pitfall은 모든 item에 flex: 1을 붙이는 것입니다. 카드와 입력창에는 유용하지만 브랜드와 버튼은 불필요하게 늘어납니다. 두 번째 Pitfall은 min-width: 0을 빠뜨리는 것입니다. 긴 제목과 URL을 넣어 보지 않으면 출시 후에야 가로 스크롤을 발견할 수 있습니다. 세 번째 Pitfall은 자식 margin으로 간격을 관리하는 것입니다. 줄바꿈이 생기면 마지막 줄의 여백이 어긋납니다. 네 번째 Pitfall은 order로 시각 순서를 바꾸고 키보드 순서를 확인하지 않는 것입니다.

검수는 세 단계로 진행합니다. 먼저 HTML 태그와 CSS 중괄호가 맞는지 봅니다. 다음으로 360px, 720px, 1024px에서 가로 스크롤, 찌그러진 버튼, 읽기 어려운 입력창을 확인합니다. 마지막으로 Claude Code에 reviewer 역할을 맡겨 “불필요한 선언, 접근성 위험, 모바일 overflow 가능성”을 다시 찾게 합니다.

직접 확인한 결과

위 HTML과 CSS를 로컬 페이지에 붙여 확인했습니다. 카드 세 개는 데스크톱에서 한 줄, 중간 폭에서 두 줄, 좁은 폭에서 한 줄로 자연스럽게 바뀌었습니다. 긴 제목을 넣었을 때도 min-width: 0과 overflow-wrap: anywhere 덕분에 가로 스크롤이 생기지 않았습니다. 반복해서 쓸 프롬프트와 템플릿은 Claude Code 제품에서, 팀 도입과 리뷰 체계는 교육 및 상담에서 이어서 정리할 수 있습니다.