PatternFly로 개발하기

PatternFly로 개발하기

PatternFly 디자인 시스템을 실제 코드로 구현하려면 환경을 준비하고 React 또는 HTML/CSS 라이브러리를 설정해야 해요. 이 페이지에서 개발을 시작하기 위한 단계를 하나씩 살펴볼게요.

출처: Develop with PatternFly

본문

시작하기

PatternFly로 개발하려면 다음 단계를 순서대로 거쳐야 해요:

  • PatternFly 디자인 시스템 알아보기 — PatternFly의 모든 요소에 익숙해져 보세요.
  • 디자인 토큰 시스템 알아보기 — 디자인 토큰을 이용하면 색상, 그림자, 간격 등 일관된 PatternFly 스타일로 인터페이스를 만들 수 있어요.
  • 패키지 매니저 설치하기 — 필요한 모든 PatternFly 패키지를 설치·업데이트·구성하는 데 쓰여요. npm이나 Yarn을 추천해요.
  • 환경 구성하기 — React 및/또는 HTML/CSS 라이브러리로 시작할 수 있도록 환경을 설정하세요.

React로 개발하기

정보 알림: 버전 지원

PatternFly는 한 번에 가장 최근의 React 2개 버전을 지원해요. PatternFly 6은 현재 React 17, 18, 19를 지원합니다.

PatternFly의 React 라이브러리에는 일관된 마크업·스타일·동작으로 인터페이스를 만들 수 있는 컴포넌트 모음이 들어 있어요. 이 라이브러리는 여러 React 패키지로 구성되며, 다음과 같은 npm 패키지로 배포됩니다:

  • @patternfly/react-core: 대부분의 React 핵심 컴포넌트.
  • @patternfly/react-charts: PatternFly 차트 컴포넌트.
  • @patternfly/react-code-editor: Monaco 코드 편집기를 감싼 PatternFly 래퍼.
  • @patternfly/react-icons: React 컴포넌트 형태의 PatternFly 아이콘.
  • @patternfly/react-styles: CSS-in-JS 기능.
  • @patternfly/react-table: PatternFly 테이블 컴포넌트.
  • @patternfly/react-tokens: PatternFly의 CSS 변수를 React에서 쓸 수 있도록 JavaScript 객체로 변환한 것.

이 패키지들은 함께 유지·관리돼요. 어떤 버전들이 서로 호환되는지 확인하려면 릴리스 하이라이트를 살펴보세요.

다음과 같은 구성을 지원해요:

  • TypeScript
  • Webpack
  • Jest
  • Editor

PatternFly React 설치 및 구성

새 프로젝트

샘플 프로젝트로 PatternFly를 시작하고 싶다면 PatternFly React seed를 사용할 수 있어요. 새 PatternFly 프로젝트를 빠르게 시작하도록 돕는 오픈소스 빌드 스캐폴딩 유틸리티예요.

시작하려면:

  • React seed를 포크하세요:
    • TypeScript: PatternFly React seed 프로젝트를 포크하고 클론합니다.
    • JavaScript: PatternFly React seed 프로젝트의 JavaScript 브랜치를 포크하고 클론합니다.
    • 리포를 포크·클론하는 방법은 GitHub Help를 참고하세요.
  • 프로젝트를 설치하세요: React seed README에 나온 단계를 따라 설치합니다.

기존 프로젝트

기존 프로젝트를 PatternFly로 마이그레이션하려면 다음 두 방법 중 하나로 PatternFly React를 설치·구성해야 해요.

  • npm을 사용하는 경우 다음 명령을 실행하세요:
npm install @patternfly/react-core --save
  • Yarn을 사용하는 경우 다음 명령을 실행하세요:
yarn add @patternfly/react-core

아이콘 사용하기

PatternFly는 Red Hat UI 아이콘(rh-ui-*)을 사용하며, 이는 @patternfly/react-icons 패키지에서 제공돼요.

react-icons 패키지에서 React 컴포넌트로 아이콘을 바로 임포트해 프로젝트에서 사용할 수 있어요:

import { RhUiArrowRightIcon } from '@patternfly/react-icons';

추가 가이드와 구현 예시는 icon 컴포넌트와 iconography foundations 페이지를 참고하세요.

Patternfly 스타일 임포트하기

PatternFly는 @patternfly/react-styles 패키지를 번역 계층으로 사용해서 PatternFly HTML/CSS 라이브러리의 스타일을 참조해요. PatternFly React로 개발할 때는 앱의 최상위 레벨에 다음 import를 포함해 PatternFly 스타일을 불러오세요:

import '@patternfly/react-core/dist/styles/base.css';

PatternFly React를 쓰면서 PatternFly HTML/CSS 라이브러리에서 직접 CSS를 임포트하면, PatternFly React가 @patternfly/react-styles를 통해 내부적으로 이미 스타일을 불러오므로 브라우저에서 스타일시트가 중복될 수 있어요.

HTML/CSS로 개발하기

PatternFly HTML/CSS 라이브러리에는 일관된 PatternFly 마크업과 스타일로 인터페이스를 만들 수 있는 코드 샘플 모음이 들어 있어요.

3개의 모듈(layouts, components, utilities) 각각은 Sass(.scss)와 CSS 파일을 제공하며, 이를 빌드 환경에 포함하거나 페이지 헤더에서 불러올 수 있어요. 요소를 덮어써야 한다면 CSS를 수동으로 덮어쓰기보다 Sass 파일의 변수를 확장하는 방식을 권장해요.

PatternFly를 설치하면 패키지에 다음이 포함돼요:

  • 컴파일된 라이브러리 전체가 담긴 단일 파일: node_modules/@patternfly/patternfly/patternfly.css
  • 각 컴포넌트가 개별 컴파일된 파일들: node_modules/@patternfly/patternfly/<ComponentName>/styles.css
  • 라이브러리 전체 소스가 담긴 단일 파일: node_modules/@patternfly/patternfly/patternfly.scss
  • 각 컴포넌트의 개별 소스 파일들: node_modules/@patternfly/patternfly/<ComponentName>/styles.scss

이 파일들을 사용해서 라이브러리를 소비해요. 권장 소비 방식은 프로젝트마다 달라질 수 있어요.

PatternFly HTML/CSS 설치 및 구성

  • npm을 사용해 다음 명령으로 HTML/CSS 라이브러리를 설치하세요:
npm install @patternfly/patternfly --save
  • 방금 설치한 패키지로 이동해 PatternFly CSS 스타일시트인 patternfly.css를 찾아 프로젝트의 CSS 디렉터리로 복사하세요.
  • HTML 파일에서 CSS 파일 목록 맨 아래에 다음 줄을 추가해 새 PatternFly 스타일시트를 링크하세요.

이렇게 하면 PatternFly 스타일이 앱에 이미 존재하는 어떤 것보다 우선 적용돼요.

  • 프로젝트에서 PatternFly 유틸리티를 쓰려면 utilities 파일인 patternfly-addons.css를 찾아 프로젝트의 CSS 디렉터리로 복사하세요.
  • HTML 파일의 CSS 파일 목록 맨 아래에 다음 줄을 추가하세요.

아이콘 사용하기

React와 마찬가지로 HTML/CSS 구현에서도 @patternfly/react-icons 패키지를 사용할 수 있어요.

@patternfly/react-icons/dist/static 디렉터리에서 개별 아이콘별 .svg 파일(예: rh-ui-arrow-right.svg)을 코드에서 직접 참조해 필요한 SVG를 추가해서 사용할 수 있어요:

npm install @patternfly/react-icons --save
<img src="node_modules/@patternfly/react-icons/dist/static/rh-ui-arrow-right.svg" />

추가 가이드와 구현 예시는 icon 컴포넌트와 iconography foundations 페이지를 참고하세요.

Font Awesome 아이콘(레거시)

PatternFly는 예전에 Font Awesome 5의 아이콘 사용을 권장했어요. 지금은 Red Hat 아이콘을 권장하지만, Font Awesome은 여전히 PatternFly에 포함되어 있으며 다음 2가지 방식으로 사용할 수 있어요:

  • PatternFly에 내장: 기본적으로 Font Awesome은 PatternFly CSS 파일의 일부로 포함돼요. 이 아이콘 폰트 패밀리를 사용하기 위해 추가로 할 일은 없어요.
  • CDN으로 사용: 기본 방식 대신 Font Awesome 5의 CDN을 사용하려면 다음 단계를 완료해야 해요.
    • sass-utilities/scss-variables.scss 파일(소스 node_modules/@patternfly/patternfly/에서)에 다음을 포함하도록 업데이트하세요:
$pf-v6-global--enable-fontawesome-cdn: true !default;
  • 빌드 프로세스의 일부로 PatternFly를 빌드하세요.

테스트

많은 PatternFly 컴포넌트가 자동화 테스트 환경을 만들고 유지하는 부담을 줄여주도록 설계된 OUIA(Open UI Automation) 지침을 따르고 있어요. OUIA에 대한 자세한 내용과 지침을 준수하는 컴포넌트 전체 목록은 개발자 리소스에서 확인할 수 있어요.

지원되는 브라우저와 운영체제

PatternFly는 다음 브라우저의 최신 2개 주요 버전을 지원해요:

  • Chrome
  • Firefox
  • Safari
  • Edge

Breaking changes

Breaking change란 PatternFly로 만든 UI가 제대로 작동하도록 하기 위해 개입이 필요한 만큼 디자인 시스템에 큰 변경이 가해진 것을 뜻해요. 이런 변경은 PatternFly 기능의 코드와 디자인 양쪽에서 일어날 수 있어요. 주요하고 예상치 못한 중단을 최소화하기 위해 PatternFly는 일반적으로 breaking change를 주요 버전 릴리스에 한정하며, 다음과 같은 예외가 있어요:

  • 주요 릴리스 일정 밖에서 보고된 치명적 버그 수정.
  • "beta"로 표시된 컴포넌트와 기능의 업데이트.

디자인 breaking changes

PatternFly 디자인의 breaking change에는 UI를 바꾸고 사용자 경험을 크게 방해할 시각적 변경이 포함돼요. UI의 적절한 시각적 작동을 복원하려면 변경을 반영한 의도적인 업데이트가 필요해요.

이런 변경에는 다음이 포함돼요:

  • 컴포넌트 스타일의 중대한 변경 — 사용자를 충분히 혼란스럽게 할 만큼 달라질 수 있어요.
  • UI에서 콘텐츠 레이아웃을 원하지 않는 방식으로 강제 변경하는 텍스트나 스페이서 크기의 증가.

코어 CSS breaking changes

코어 CSS 라이브러리의 breaking change는 다음과 같은 코드 변경으로 인해 발생해요:

  • CSS 변수:
    • CSS 변수를 제거하거나 이름을 바꾸는 경우.
    • CSS 변수의 역할을 재용도화하거나 변경하는 경우.
    • 시맨틱 레이어에서 토큰 간 관계를 변경하는 경우(--pf-t로 시작하고 숫자로 끝나지 않는 토큰).
  • 클래스 이름:
    • 클래스를 제거하거나 이름을 바꾸는 경우.
    • 이전에 필수가 아니었던 클래스를 필수로 만드는 경우.

React breaking changes

React 라이브러리의 breaking change는 다음과 같은 코드 변경으로 인해 발생해요:

  • 컴포넌트 props:
    • prop을 제거하는 경우.
    • prop의 이름·타입·역할·기능을 변경하는 경우.
    • 이전에 필수가 아니었던 prop을 필수로 만드는 경우.
  • 의존성:
    • 컴포넌트 동작을 바꾸는 변경.
    • 소비자의 빌드 프로세스를 바꾸는 변경.
    • 이벤트 핸들러 시그니처를 바꾸는 변경.

더 알아보기 (Learn more)