@newtil/materials

Material Design 3 를 CSS 로 구현한 m3- 컴포넌트 라이브러리.

Google M3 스펙의 버튼·카드·다이얼로그·내비게이션 등을 순수 CSS 클래스로 제공합니다. 모든 시각 속성은 @newtil/design-tokens 의 변수 위에서 동작하므로 토큰만 바꾸면 전체가 일관되게 바뀌고, 다크모드도 토큰 층에서 해결됩니다. 커스터마이징은 타입 → 옵션 클래스 → CSS 변수 3단계 순서로 합니다. 아이콘(m3-icon)은 Google Fonts 의 Material Symbols 폰트를 사용하므로 런타임에 폰트 네트워크 접근이 필요합니다.

설치

npm install @newtil/materials

@newtil/design-tokens 는 의존성으로 함께 설치됩니다.

빠른 시작

JS 번들러(Vite, Webpack 등)에서는 패키지를 그대로 가져오면 CSS 가 로드됩니다.

import "@newtil/materials";

CSS 파일만 필요하면 index.css 서브패스를 사용합니다. 쓰는 컴포넌트가 몇 개뿐이면 base.css + component/<이름>.css 로 골라 가져옵니다(0.4.27, 아래).

@import "@newtil/materials/index.css";

index.css 하나에 design-tokens · reset · Material Symbols 폰트 @import · 모든 m3-* 컴포넌트가 들어 있습니다(142KB, gzip 25KB). CSS 는 tree-shaking 이 없으므로 안 쓰는 컴포넌트도 그대로 나갑니다.

컴포넌트를 골라 쓰려면 바탕(base.css: 레이어 순서 · reset · 폰트)과 컴포넌트 파일을 가져옵니다. 이 경로엔 design-tokens 사본이 없으니 토큰을 먼저 부릅니다.

@import "@newtil/design-tokens";
@import "@newtil/materials/base.css";
@import "@newtil/materials/component/m3-btn.css";
@import "@newtil/materials/component/m3-nav-bar.css";

파일 이름은 dist/component/ 의 목록(= css/component/m3/ 의 파일명)과 같습니다. icon:이름 클래스를 쓰면 component/icon-essential.css 도 함께.

<!-- 버튼: filled 가 기본. 타입·크기·색은 옵션 클래스로 -->
<button class="m3-btn">저장</button>
<button class="m3-btn btn:outlined btn-size:sm">취소</button>
<button class="m3-btn btn:tonal btn-color:danger btn-icon:leading">
  <i class="m3-icon icon:delete"></i>삭제
</button>

<!-- 카드 -->
<div class="m3-card card:outlined">
  <div class="card-header">
    <h3 class="card-headline">카드 제목</h3>
    <p class="card-subhead">부제목</p>
  </div>
  <div class="card-content">
    <p>본문 내용</p>
  </div>
  <div class="card-actions">
    <button class="m3-btn btn:text">취소</button>
    <button class="m3-btn">확인</button>
  </div>
</div>

문서

• 문서 사이트: https://newlecture-corp.github.io/newtil-materials/ — 모든 컴포넌트의 라이브 프리뷰·옵션·Variable API
• CHANGELOG.md — 버전별 변경 사항
• COMPONENT-GUIDE.md — 컴포넌트 CSS 작성 규칙(변수 선언·옵션 클래스·상태 처리·네이밍)

컴포넌트

css/component/m3/ 의 파일 하나가 컴포넌트 하나입니다. 접두사 m3- 는 컴포넌트 클래스, 옵션 클래스는 이름:값 형식(btn:outlined, btn-size:lg)입니다.

| 파일 | 클래스 | 설명 | 문서 | |------|--------|------|------| | m3-btn.css | m3-btn | 버튼. filled(기본)·elevated·tonal·outlined·text, 크기 5단계, 색상 변형 | 버튼 | | m3-fab.css | m3-fab | Floating Action Button. fab:small·fab:large·fab:extended | 버튼 | | m3-icon-btn.css | m3-icon-btn | 아이콘 버튼. standard(기본)·icon-btn:filled·icon-btn:tonal·icon-btn:outlined, 토글 상태 | 버튼 | | m3-text-field.css | m3-text-field | 텍스트 입력 필드. filled(기본)·field:outlined, 라벨 위치·크기 옵션 | 입력 | | m3-checkbox.css | m3-checkbox | 체크박스 | 입력 | | m3-radio-btn.css | m3-radio | 라디오 버튼 | 입력 | | m3-switch.css | m3-switch | 스위치(토글) | 입력 | | m3-slider.css | m3-slider | 슬라이더 | 입력 | | m3-form.css | m3-form | 폼 레이아웃(헤더·필드·액션·메시지). M3 스펙에 없는 newtil 확장 | 입력 | | m3-card.css | m3-card | 카드. elevated(기본)·card:filled·card:outlined, 헤더·콘텐츠·액션 영역 | 컨테이너 | | m3-dialog.css | m3-dialog | 다이얼로그(<dialog> 요소 기반) | 컨테이너 | | m3-bottom-sheet.css | m3-bottom-sheet | 바텀 시트. standard(기본)·sheet:modal | 컨테이너 | | m3-chips.css | m3-chip | 칩. chip:elevated·chip:selected 옵션 | 컨테이너 | | m3-badge.css | m3-badge | 배지(숫자·점) | 커뮤니케이션 | | m3-progress.css | m3-progress | 프로그레스 인디케이터. linear(기본)·progress:circular·progress:indeterminate | 커뮤니케이션 | | m3-snackbar.css | m3-snackbar | 스낵바 | 커뮤니케이션 | | m3-tooltip.css | m3-tooltip | 툴팁. plain(기본)·tooltip:rich | 커뮤니케이션 | | m3-tabs.css | m3-tabs | 탭. primary(기본)·tabs:secondary | 내비게이션 | | m3-top-app-bar.css | m3-top-app-bar | 상단 앱 바. 기본은 static, bar:fixed 로 상단 고정 | 내비게이션 | | m3-nav-bar.css | m3-nav-bar | 하단 내비게이션 바. 기본은 static, nav-bar:fixed 로 하단 고정 | 내비게이션 | | m3-nav-rail.css | m3-nav-rail | 내비게이션 레일. 기본은 static, rail:fixed 로 좌측 고정 | 내비게이션 | | m3-nav-drawer.css | m3-nav-drawer | 내비게이션 드로어. standard(인라인)·modal(오버레이) | 내비게이션 | | m3-menu.css | m3-menu | 메뉴(드롭다운 항목 목록) | 내비게이션 | | m3-list.css | m3-list | 리스트. leading·trailing·아바타·보조 텍스트·구분선 | 내비게이션 | | m3-layout.css | m3-layout | 적응형 페이지 레이아웃. 화면 폭에 따라 nav-bar → rail → drawer 자동 전환 | 레이아웃 | | m3-divider.css | m3-divider | 구분선(inset·middle-inset·vertical) | 레이아웃 | | m3-icon.css | m3-icon | Material Symbols 아이콘. 크기·색·채움·굵기 옵션 | 아이콘 | | m3-deco.css | m3-deco | 아이콘+텍스트 장식. nav-bar·nav-rail 의 항목으로 사용 | 아이콘 | | icon-essential.css | icon:* | 자주 쓰는 아이콘 60개의 icon:이름 클래스와 data-icon 리가처 지원 | 아이콘 |

newtil 패밀리

| 패키지 | 설명 | 문서 | |--------|------|------| | @newtil/design-tokens | CSS 변수(토큰) — 색·간격·글꼴·모서리·그림자·층. 모든 패키지의 바닥 | https://newlecture-corp.github.io/newtil-design-tokens/ | | @newtil/css | 실제 CSS 속성명 기반 유틸리티 클래스 + JIT | https://newlecture-corp.github.io/newtil-css/ | | @newtil/components | n- 접두사 기본 컴포넌트 — prose·table·layout·resize-handle | https://newlecture-corp.github.io/newtil-components/ | | @newtil/materials | Material Design 3 구현 m3- 컴포넌트 (이 패키지) | https://newlecture-corp.github.io/newtil-materials/ | | @newtil/editor | 마크다운↔HTML 양방향 편집기 웹 컴포넌트(React/Vue 래퍼) | https://newlecture-corp.github.io/newtil-editor/ | | @newtil/drawing | 캡처 위에 화살표·상자·글자를 그리는 그림판(PNG+JSON) | https://newlecture-corp.github.io/newtil-drawing/ |

개발

npm install
npm run build        # css/ → dist/ (rollup + postcss)
npm run docs:dev     # 문서 사이트 로컬 실행 (dist/index.css 를 읽으므로 build 먼저)
npm run docs:build   # 문서 사이트 빌드 → docs/.vitepress/dist

컴포넌트 CSS 를 추가·수정할 때는 COMPONENT-GUIDE.md 의 규칙(변수 선언 → 베이스 스타일 → 옵션 클래스는 변수만 변경)을 따릅니다. 문서 사이트는 main 푸시 시 GitHub Actions 로 배포됩니다.

라이선스

MIT