Utility 클래스
네이밍 원칙
CSS를 아는 사람이면 newtil-css를 바로 쓸 수 있어야 한다.
Tailwind는 p-4, bg-blue-500 같은 자체 명칭을 사용합니다. newtil-css는 실제 CSS 속성명을 그대로 쓰거나 누구나 유추할 수 있는 축약을 제공합니다.
.padding:4 → padding: var(--space-4)
.p:4 → 같은 것 (축약)
.background-color:primary → background-color: var(--color-primary)
.bg:primary → 같은 것 (축약)유틸 활용하기
유틸만 사용하기
디자인 시스템의 토큰만 활용해서 컴포넌트를 직접 만들 수 있습니다. 라이브러리에 없는 모양이나 빠르게 프로토타이핑할 때 유용합니다.
버튼 만들기
소스 코드 보기
카드 만들기
소스 코드 보기
컴포넌트에 유틸로 커스텀하기
@newtil/materials(m3-) 같은 컴포넌트 라이브러리 위에 유틸리티를 얹으면, 컴포넌트의 기본 모양은 유지하면서 특정 상황에 맞는 조정을 빠르게 할 수 있습니다. 이 문서 사이트에는 materials 가 로드되어 있지 않아 코드로만 보입니다.
버튼에 간격/정렬 추가
<div class="d:flex g:4 jc:center p:5 bg:surface-2 bdr:4">
<button class="m3-btn">기본</button>
<button class="m3-btn btn:outlined">Outlined</button>
<button class="m3-btn btn-color:danger">삭제</button>
</div>카드를 그리드 레이아웃에 배치
<div class="d:grid gtc:3 g:5">
<div class="m3-card card:outlined">첫 번째 카드</div>
<div class="m3-card card:outlined">두 번째 카드</div>
<div class="m3-card card:outlined">세 번째 카드</div>
</div>컴포넌트 변수를 인라인 스타일로 재정의
컴포넌트 변수는 일반 CSS 변수이므로 인라인 스타일로 오버라이드할 수 있습니다.
<button class="m3-btn" style="--btn-background-color: purple; --btn-border-radius: 0.25rem;">
변수 오버라이드
</button>함께 쓰기 좋은 이유
@newtil/materials 와 @newtil/components 는 모양을 컴포넌트 변수로 노출하고, @newtil/css 는 배치·간격·색을 유틸리티 클래스로 조정합니다. 세 패키지가 같은 design-tokens를 공유해서 색/간격/그림자가 자연스럽게 맞습니다.
전체 카테고리 목록
Core
| 카테고리 | 속성 | 축약 |
|---|---|---|
| Display | display:flex | d:flex |
| Position | position:absolute, top:4, z-index:modal | pos:absolute, z:modal |
| Spacing | margin:4, margin-top:3, margin-x:auto, padding:5, gap:3 | m:4, mt:3, mx:auto, p:5, g:3 |
| Sizing | width:full, height:11, min-width:14, max-height:screen-h | w:full, h:11, min-w:14, max-h:screen-h |
| Color | color:primary, background-color:surface, border-color:border | c:primary, bg:surface, bdc:border |
| Typography | font-size:body, font-weight:bold, line-height:normal, text-align:center | fs:body, fw:bold, lh:normal, ta:center |
| Border | border-width:1, border-style:solid, border-radius:3 | bdw:1, bds:solid, bdr:3 |
| Flexbox | flex-direction:column, justify-content:center, align-items:center | fd:column, jc:center, ai:center |
| Grid | grid-template-columns:3, grid-column:span-2 | gtc:3, gcs:span-2 |
| Effects | opacity:50, box-shadow:md, cursor:pointer, overflow:hidden | op:50, bsh:md, cur:pointer, of:hidden |
| Transition | transition:default, transition-duration:fast | tr:default, tdur:fast |
| Transform | translate-x:4, rotate:45, scale:110 | trx:4, rot:45, scl:110 |
| Outline | outline-width:2, outline-style:solid, outline-color:focus-ring | olw:2, ols:solid, olc:focus-ring |
| Background | background-size:cover, background-position:center | bgs:cover, bgp:center |
| Font Family | font-family:sans, font-family:mono | ff:sans, ff:mono |
| Text Extras | text-shadow:md, text-wrap:balance, text-overflow:ellipsis | tsh:md, tw:balance, to:ellipsis |
추가 카테고리
| 카테고리 | 속성 예시 | 축약 |
|---|---|---|
| Filter | blur:md, brightness:110, grayscale:100 | blr:md, brt:110, gray:100 |
| Backdrop Filter | backdrop-blur:lg | bdblr:lg |
| Aspect Ratio | aspect-ratio:video, aspect-ratio:square | ar:video, ar:square |
| Object | object-fit:cover, object-position:center | ofit:cover, opos:center |
| Animation | animation:spin, animation:pulse | anim:spin, anim:pulse |
| Scroll | scroll-snap-type:y, scroll-behavior:smooth | sst:y, sb:smooth |
| Interaction | user-select:none, pointer-events:none | us:none, pe:none |
| Blend | mix-blend-mode:multiply, isolation:isolate | mbm:multiply, iso:isolate |
| SVG | fill:primary, stroke:border, stroke-width:1 | — |
| Tables | table-layout:fixed, border-collapse:collapse | tl:fixed |
| Lists | list-style-type:disc | lst:disc |
| Columns | column-count:3 | cc:3 |
| Legacy | float:left, clear:both | fl:left, cl:both |
| Logical | margin-inline:4, padding-block:3, inset-inline:0 | — |
합성 유틸 (Composite)
| 클래스 | 효과 |
|---|---|
.truncate | 한 줄 말줄임표 (overflow:hidden + text-overflow:ellipsis + white-space:nowrap) |
.line-clamp:3 | 3줄 말줄임표 |
.sr-only | 시각 숨김, 스크린리더 접근 가능 |
.not-sr-only | sr-only 해제 |
.center | flex 중앙정렬 |
.center-col | flex column 중앙정렬 |
.fixed-center | absolute 중앙 (translate -50%) |
.stack:3 | flex column + gap:3 |
.hstack:3 | flex row + align-center + gap:3 |
단계 밖의 값: 속성:ex
토큰 단계(width:1…, padding:4)에 없는 값이 필요하면 속성:ex 클래스를 붙이고 값은 같은 요소의 --속성-ex 변수로 줍니다. 모든 속성:값 클래스에 ex 가 하나씩 있습니다(413개).
<div class="width:ex" style="--width-ex: 20px">…</div>
<div class="padding-x:ex" style="--padding-x-ex: 1.25rem">…</div> <!-- 합성 속성은 변수 하나로 좌우 -->
<img class="blur:ex" style="--blur-ex: 4px"> <!-- filter: blur(var(--blur-ex)) -->
<p class="line-clamp:ex" style="--line-clamp-ex: 3">…</p> <!-- 고정 선언(display 등)은 그대로, 줄 수만 변수 -->- 축약(
w:ex,px:ex)과 반응형·상태 접두(sm:w:ex,hover:color:ex)가 모두 됩니다. 변수 이름은 축약이 아니라 전체 속성명 기준입니다(w:ex도--width-ex). - 규칙이 고정이므로 JIT 없이 CDN
<link>만으로 동작합니다. JIT 는 쓰인ex클래스만 골라 냅니다. - Tailwind 의
w-[20px]와 달리 값이 클래스 이름이 아니라style에 있어, DOM 을 직접 다루는 도구가 값을 바꿀 때 CSS 를 다시 만들 필요가 없습니다. - 사용 원칙: 토큰 단계 → 컴포넌트 옵션 →
ex. 페이지의ex개수가 아직 부품이 못 담은 값의 수이고, 다음 토큰·컴포넌트 후보를 고르는 척도입니다.
값 체계
Spacing / Sizing (rem 기반, 4px 그리드)
| 인덱스 | 값 (rem) | 약 px |
|---|---|---|
| 0 | 0 | 0 |
| 1 | 0.125rem | 2px |
| 2 | 0.25rem | 4px |
| 3 | 0.5rem | 8px |
| 4 | 0.75rem | 12px |
| 5 | 1rem | 16px |
| 6 | 1.25rem | 20px |
| 7 | 1.5rem | 24px |
| 8 | 2rem | 32px |
| 9 | 2.5rem | 40px |
| 10 | 3rem | 48px |
| 11 | 4rem | 64px |
| 12 | 5rem | 80px |
| 13 | 6rem | 96px |
| 14 | 8rem | 128px |
크기 (width / height / min-* / max-*)
크기 클래스는 위 spacing 인덱스(w:5 → var(--space-5))에 리터럴 값을 더한 것입니다. w:1-2 h:screen-h w:full 같은 분수·뷰포트·키워드 값은 토큰이 아니라 생성기가 직접 넣는 리터럴(50%, 100vh, 100%)입니다. 클래스 이름은 그대로이며 CSS 변수로는 노출되지 않습니다.
| 종류 | 값 |
|---|---|
| 분수 | 1-2 1-3 2-3 1-4 3-4 1-5 2-5 3-5 4-5 1-6 5-6 1-12 5-12 7-12 11-12 |
| 뷰포트 | screen-w screen-w-25/50/75 screen-h screen-h-25/50/75 |
| 키워드 | full half auto none min-content max-content fit-content |
글꼴 크기
글꼴 크기 클래스는 역할명만 있습니다: font-size:caption body-sm body body-lg heading-sm heading-md heading-lg heading-xl display (축약 fs:). 티셔츠명(xs…4xl)은 토큰 별칭만 남아 있고 클래스는 만들지 않습니다.
색상
→ Design Tokens 가이드 참고