Styling

Confy-ui로 스타일링하는 방법.

Introduction

Confy-ui는 기본적으로 스타일링 시스템을 제공하지 않습니다. css 또는 sx prop이 없으며, 내부적으로 스타일링 라이브러리를 사용하지 않습니다. 기본적으로 순수 CSS로 구축되어 있습니다.

스타일링 기술을 선택하는 데 있어 오버헤드가 없습니다.

What you get

Confy-ui의 구성 요소는 상대적으로 폐쇄적입니다. 즉, 쉽게 오버라이드할 수 없는 스타일 세트를 가지고 있습니다. 구성 요소는 props와 테마 구성을 통해 사용자 정의할 수 있습니다.

그러나 Confy-ui 구성 요소를 지원하는 동일한 CSS 변수를 사용할 수 있습니다. 이러한 토큰을 사용하여 원래 테마에 자연스럽게 어울리는 사용자 정의 구성 요소를 만들 수 있습니다. 토큰 시스템에 대한 변경 사항은 파괴적인 것으로 간주됩니다.

특정 토큰에 대한 자세한 내용은 테마 섹션의 해당 가이드를 참조하세요.

Overriding styles

간단한 스타일 오버라이드를 넘어서, 구성 요소를 그대로 사용하거나 동일한 빌딩 블록을 사용하여 자신의 버전을 만드는 것을 권장합니다.

대부분의 구성 요소는 className 및 style props를 가지고 있지만, 많은 스타일을 오버라이드해야 하는 경우, 이는 기존 props와 테마 구성을 통해 필요한 것을 달성해야 한다는 좋은 신호입니다.

• 기존 props와 테마 구성을 통해 필요한 것을 달성해 보세요.
• 기본 토큰 시스템을 조정하여 디자인을 달성할 수 있는지 확인하세요.

• Confy-ui가 프로젝트에 적합한지 재고해 보세요.

Tailwind

Tailwind는 훌륭합니다. 그러나 Confy-ui와 Tailwind를 함께 사용할 계획이라면, Tailwind의 사용 방식이 구성 요소 내부로 복잡한 스타일을 생성하도록 유도할 수 있다는 점을 유의하세요.

Tailwind는 다른 스타일링 패러다임으로, props, 토큰 및 공유된 빌딩 블록 세트를 통해 사용자 정의가 이루어지는 폐쇄형 구성 요소 시스템과 잘 혼합되지 않을 수 있습니다.

Custom components

사용자 정의 구성 요소를 만들어야 하는 경우, Confy-ui가 사용하는 동일한 빌딩 블록을 사용하세요:

• 구성 요소를 지원하는 테마 토큰

Common issues

z-index conflicts

기본적으로 포털된 Confy-ui 구성 요소는 어떤 순서로 중첩되고 쌓일 수 있습니다. 예를 들어, 팝오버를 열고 다이얼로그를 열고, 그 다이얼로그가 다시 다른 팝오버를 열 수 있습니다. 이들은 모두 열린 순서에 따라 서로 위에 쌓입니다.

자신의 구성 요소를 만들 때 z-index 충돌을 피하기 위해 다음 규칙을 사용하세요:

• auto, 0 또는 드문 경우에만 -1을 제외한 z-index 값을 사용하지 마세요.
• 서로 쌓여야 하는 요소는 포털에서 렌더링하세요.

주 콘텐츠와 포털 콘텐츠는 루트 <Theme> 컴포넌트의 스타일이 생성하는 쌓기 컨텍스트에 의해 분리됩니다. 이를 통해 z-index에 대한 걱정 없이 포털 콘텐츠를 주 콘텐츠 위에 쌓을 수 있습니다.

Next.js import order

Next.js 13.0부터 14.1까지, app/**/layout.tsx에서 CSS 파일의 가져오기 순서는 보장되지 않으므로 Confy-ui가 올바르게 작성되었더라도 자신의 스타일을 덮어쓸 수 있습니다:

import "@confy-ui/react/themes/styles.css";
import "./my-styles.css";

이 Next.js 문제는 간헐적으로 발생할 수 있으며, 개발 또는 프로덕션에서만 발생할 수 있습니다.

해결 방법으로는 postcss-import를 통해 모든 CSS를 먼저 단일 파일로 병합하고, 그 파일만 레이아웃에 가져오는 방법이 있습니다. 또는 page.tsx 파일에 스타일을 직접 가져오는 것도 가능합니다.

Tailwind base styles

Tailwind v3부터, @tailwind 지시문으로 생성된 스타일은 원래 가져오기 순서와 관계없이 일반적으로 가져온 CSS 뒤에 추가됩니다. 특히, Tailwind의 버튼 리셋 스타일은 Confy-ui 버튼과 충돌하여 특정 버튼이 배경색 없이 렌더링될 수 있습니다.

해결 방법:

• @tailwind base를 사용하지 마세요.
• Tailwind와 Confy-ui에 대해 별도의 CSS 레이어를 설정하세요.
• postcss-import를 설정하고, Confy-ui 스타일 이전에 @import tailwindcss/base를 통해 Tailwind 기본 스타일을 수동으로 가져오세요.

Missing styles in portals

Confy-ui 프로젝트에서 사용자 정의 포털을 렌더링하면, 포털은 자연스럽게 루트 <Theme> 컴포넌트 외부에 나타나므로 대부분의 테마 토큰과 스타일에 접근할 수 없습니다. 이를 해결하려면 포털 콘텐츠를 다른 <Theme>로 감싸세요:

import { Dialog } from "@confy-ui/react/primitives";
import { Theme } from "@confy-ui/react/themes";

function MyCustomDialog() {
	return (
		<Dialog.Root>
			<Dialog.Trigger>Open</Dialog.Trigger>
			<Dialog.Portal>
				<Theme>
					<Dialog.Overlay />
					<Dialog.Content>
						<Dialog.Title />
						<Dialog.Description />
						<Dialog.Close />
					</Dialog.Content>
				</Theme>
			</Dialog.Portal>
		</Dialog.Root>
	);
}

Confy-ui의 Dialog 및 Popover와 같은 구성 요소는 이미 이를 처리하므로, 사용자 정의 포털 구성 요소를 만들 때만 필요합니다.

Complex CSS precedence

일반적으로, 사용자 정의 CSS가 Confy-ui 스타일을 오버라이드하도록 하기를 원할 것입니다. 그러나 자연스럽게 반대의 기대를 할 수 있는 경우도 있습니다.

예를 들어, 브라우저의 기본 여백을 재설정하는 간단한 단락 스타일을 고려해 보세요:

.my-paragraph {
	margin: 0;
}

Box에서 asChild를 통해 사용자 정의 단락에 여백 prop을 적용할 수 있습니다:

import "@confy-ui/react/themes/styles.css";
import "./my-styles.css";

function MyApp() {
	return (
		<Theme>
			<Box asChild m="5">
				<p className="my-paragraph">My custom paragraph</p>
			</Box>
		</Theme>
	);
}

그러나 이는 직관적으로 작동하지 않을 것입니다. 사용자 정의 스타일이 Confy-ui 스타일 뒤에 가져와지므로 여백 prop을 오버라이드합니다. 해결 방법으로는 Confy-ui가 제공하는 별도의 tokens.css, components.css, utilities.css 파일이 있습니다. 원래 styles.css는 이러한 파일을 기반으로 구축됩니다:

import "@confy-ui/react/themes/tokens.css";
import "@confy-ui/react/themes/components.css";
import "@confy-ui/react/themes/utilities.css";

사용자 정의 스타일 뒤에 utilities.css를 가져오면 레이아웃 props가 사용자 정의 스타일과 예상대로 작동하도록 보장할 수 있습니다. 그러나 Next.js를 사용하는 경우, 위에서 언급한 가져오기 순서 문제를 염두에 두어야 합니다.

독립형 레이아웃 구성 요소를 사용하는 경우, 이러한 구성 요소에 대해서도 분할된 CSS 파일을 사용할 수 있습니다:

import "@confy-ui/react/themes/layout/tokens.css";
import "@confy-ui/react/themes/layout/components.css";
import "@confy-ui/react/themes/layout/utilities.css";