@hanzo/ui

소개

웹, 네이티브, 데스크톱을 하나의 기반으로 받치는 컴포넌트 라이브러리. 임포트는 하나, 루트는 하나, 설정할 것은 없습니다.

@hanzo/ui 은 Hanzo 의 컴포넌트 라이브러리입니다. 모든 컴포넌트는 @hanzo/gui 를 거쳐 그려집니다. React 와 React Native 를 위한 스타일 엔진으로, 스타일을 props 로 받아 웹에서는 아토믹 CSS 로 컴파일합니다. 엔진이 크로스 플랫폼이므로 라이브러리도 같습니다. 같은 Switch 가 브라우저에서는 div 로, 휴대폰에서는 네이티브 뷰로 그려집니다.

유틸리티 클래스를 조립하는 빌드는 없습니다. Tailwind 도, PostCSS 플러그인도, 컴포넌트 밑에 깔린 Radix 프리미티브도, 레지스트리도, components.json 도, 소스를 저장소로 복사하는 CLI 도 없습니다. 패키지를 설치하고 거기서 가져옵니다.

설치하고 그리기

pnpm add @hanzo/ui @hanzo/gui
main.tsx
import { Hanzo, Button } from '@hanzo/ui'

export default function App() {
  return (
    <Hanzo>
      <Button>Ship</Button>
    </Hanzo>
  )
}

설정은 이게 전부입니다. Hanzo 가 루트이고, 예전에는 앱마다 따로 하던 세 가지를 집니다. 토큰이 비추는 gui 설정, 스타일시트, 테마입니다. 가져올 CSS 도 없고 돌릴 생성기도 없습니다. 시트는 패키지를 발행할 때 만들어집니다. 모든 컴포넌트를 렌더하고 그 렌더가 낸 CSS 를 거두므로, 첫 페인트도 서버의 모든 렌더도 이미 규칙을 갖고 있습니다.

호스트가 아직 할 일은 하나입니다. 번들러에게 react-native 가 react-native-web 이라는 것을 알리는 일입니다. 별칭은 하나이고, 자리는 설치 아래 호스트별 페이지에 있습니다.

스타일은 props

스타일은 컴포넌트의 prop 이고, 반응형 스타일은 같은 prop 을 브레이크포인트 키 아래에 둔 것입니다.

import { Button, Text, XStack, YStack } from '@hanzo/ui'

<YStack gap="$4" p="$5" $md={{ p: '$8' }}>
  <Text fontSize="$5" color="$color11">
    Balance
  </Text>
  <XStack gap="$2">
    <Button>Send</Button>
    <Button variant="outline">Receive</Button>
  </XStack>
</YStack>

브레이크포인트는 모바일 퍼스트의 최소 너비입니다. $sm 은 640, $md 는 768, $lg 는 1024, $xl 은 1280 입니다. $ 로 시작하는 값은 토큰입니다. 색, 크기, 간격 램프의 한 단으로, 테마에 대해 풀립니다. 그래서 $background 는 호출부가 몰라도 라이트와 다크에서 다른 색이 됩니다. 글자 크기는 언제나 토큰이고 숫자는 아닙니다. fontSize="$3" 이지, fontSize={14} 가 아닙니다. 사람이 자기 타입 스케일을 정하면 램프의 $n 도 따라 움직입니다. 박아 둔 14 는 움직이지 않습니다. 사다리는 테마 에 있습니다.

레이아웃

스택은 flex 입니다. XStack 은 행으로, YStack 은 열로 놓고, 둘 다 gap, items, justify 를 받습니다. 그리드는 진짜 CSS 그리드이고 @hanzo/ui/grid 에 있습니다. 트랙은 자식이 아니라 컨테이너에서 나옵니다. 그리드 를 보세요.

무엇이 어디에

임포트내용
@hanzo/ui컴포넌트 API. 모든 프리미티브, 스택, 타입 스케일, 그리고 Hanzo.
@hanzo/ui/product앱 층. 차트, 페이지 크롬, 상태 태그, 상세 창, 테마 토글.
@hanzo/ui/blocks데이터로서의 내용과, 그것을 그리는 렌더러.
@hanzo/ui/gridGrid 와 Cell. 웹 전용.
@hanzo/ui/product/pure프로덕트 층이 따르는 규칙. 컴포넌트는 붙어 있지 않습니다.
@hanzo/ui/csssubstitute. 캐스케이드 없는 DOM 이 답할 수 없는 테스트용.
@hanzo/ui/next두 번들러에 웹 별칭을 넣는 Next 래퍼.

이 사이트의 카탈로그, 컴포넌트, 블록, 프로덕트 는 패키지 자체에서 읽습니다. 각 페이지는 모듈의 예제를 소스 옆에 그리고 타입을 인용합니다.

질문

Tailwind 가 필요한가요? 아닙니다. 컴포넌트는 스타일 props 를 받고, 정체는 평범한 CSS 커스텀 프로퍼티입니다. 클래스 문자열을 가진 앱이 와도 Box, sx, css 가 tw 를 거쳐 읽고 같은 props 로 바꿉니다. 패키지가 정의하지 않은 클래스로 DOM 에 닿는 것은 없습니다.

복사해서 붙이는 방식인가요? 아닙니다. 패키지를 설치하고 거기서 가져옵니다. 컴포넌트는 패키지와 함께 버전이 매겨지고, 서브패스가 풀리는 곳은 익스포트 맵입니다. 깊은 임포트는 패치를 건너서도 그대로 동작합니다.

어떤 프레임워크인가요? 번들러가 react-native 별칭을 알면 React 19 렌더러는 무엇이든 됩니다. Vite, Next, One, Expo, Tauri 페이지가 있습니다.

상업적으로 쓸 수 있나요? 쓸 수 있습니다. Apache-2.0 또는 MIT, 원하는 쪽을 고르세요.