@mp-cleared/design-system
v0.2.0
Published
Cleared design system — primitive color tokens · semantic alias (light) · typography.
Downloads
1,473
Readme
@mp-cleared/design-system
Cleared design system (lite). color tokens (primitive + semantic light alias 한 dictionary) + typography tokens. React component / theming runtime 없음.
개발·빌드·배포는 CONTRIBUTING.md, 설계 근거는 docs/ 참고.
Install
npm install @mp-cleared/design-systemCDN (plain html · mockup · 외부 데모 — 별도 번들러 없이):
<link rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@mp-cleared/[email protected]/index.css">Usage
폰트는 별도 로드 필요 (Pretendard Variable):
<link rel="stylesheet"
href="https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/web/variable/pretendardvariable-dynamic-subset.min.css">CSS (web)
.cleared-root 를 켜면 CSS variable(--gray_10 등)과 type scale class(large_title 등)가 그 하위에서 동작.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mp-cleared/[email protected]/index.css">
<body class="cleared-root">
<h1 class="large_title" style="color: var(--gray_10)">Cleared</h1>
<p class="body_1" style="color: var(--gray_40)">학업 AI 비서</p>
<button class="body_1_strong"
style="background: var(--indigo_40); color: var(--gray_100)">
시작하기
</button>
</body>번들러 환경에서 CSS만:
import '@mp-cleared/design-system/index.css';
// 또는 부분만
import '@mp-cleared/design-system/color.css';
import '@mp-cleared/design-system/typography.css';TypeScript
import { COLOR, TYPOGRAPHY, FONT_FAMILY } from '@mp-cleared/design-system';
const styles = {
brand: { color: COLOR.indigo_40 }, // primitive (원자 값)
cta: { background: COLOR.primary }, // semantic (의도)
display: { ...TYPOGRAPHY.large_title, fontFamily: FONT_FAMILY.sans },
};Subpath import:
import { COLOR } from '@mp-cleared/design-system/color';
import { TYPOGRAPHY, FONT_FAMILY, PRETENDARD_CDN } from '@mp-cleared/design-system/typography';Tokens
Color — primitive + semantic (한 dictionary)
primitive 와 semantic alias 가 같은 COLOR 객체 / 같은 color.css 안에 공존. CSS variable · TS key 모두 snake_case.
Primitive — family_NN (qds4-web 컨벤션):
- 숫자 작을수록 어두움.
gray_0=#000000 …gray_100=#ffffff, 나머지 family 는5 · 10 · 20 · 30 · 40 · 50 · 60 · 70 · 80 · 90 · 95. - Family:
gray·indigo(brand) ·purple·blue·yellow·green·red - 예:
--gray_10≈ Tailwind slate-900 ·--indigo_40= brand #4f46e5
Semantic (light) — spec §Color System 의 12개 의미 alias. primitive 의 hex 를 mirror:
| token | = primitive | hex | 역할 |
|---|---|---|---|
| primary | indigo_40 | #4f46e5 | Brand · CTA · active |
| primary_dark | indigo_20 | #3730a3 | Hover · depth |
| primary_light | indigo_90 | #e0e7ff | Background tint |
| surface | gray_95 | #f8fafc | Neutral background |
| surface_raised | gray_100 | #ffffff | Card · sheet |
| text_primary | gray_10 | #0f172a | Body |
| text_secondary | gray_50 | #64748b | Caption |
| text_muted | gray_60 | #94a3b8 | Subtle |
| accent | yellow_50 | #f59e0b | Warm highlight |
| success | green_50 | #10b981 | 완료 · 긍정 |
| danger | red_50 | #ef4444 | 위험 |
| border | gray_80 | #e2e8f0 | Subtle divider |
- TS:
COLOR.indigo_40·COLOR.primary/ CSS:var(--indigo_40)·var(--primary) - 같은 surface 안에서 layer 를 섞지 않는 걸 권장 — 의도면 전부 semantic key, 원자면 전부 primitive key. 근거: ADR-0005.
Typography — named scale
| key | size/line | weight |
|---|---|---|
| large_title | 32 / 40 | 700 |
| title_1_strong | 24 / 32 | 700 |
| title_2_strong | 20 / 28 | 600 |
| title_3_strong | 18 / 24 | 600 |
| body_1 | 16 / 24 | 400 |
| body_1_strong | 16 / 24 | 600 |
| body_2 | 14 / 20 | 400 |
| caption_1 | 12 / 16 | 500 |
| mono | 14 / 20 | 400 (monospace) |
CSS class는 .cleared-root 하위 스코프. TS는 TYPOGRAPHY.<key> ({ fontSize, lineHeight, fontWeight, fontFamily }).
알아둘 것
- Light scheme만. dark 는 미제공 — semantic light layer 만 ship (별도 minor 에서 dark 추가 예정).
- 아이콘 미포함 (v0.1 보류). 당장 필요하면 consumer가 lucide 등 직접 사용. 근거·재개안: ADR-0004.
- hex는 Tailwind v4 palette 기반 — Tailwind 쓰는 surface와 색이 정확히 일치.
문서
- CONTRIBUTING.md — 개발·빌드·배포
- docs/architecture.md — 구성·빌드·소비 SSOT
- docs/adr/ — 결정 기록 (primitive 토큰·qds4 네이밍 / React-free 이중 소비 / dist-only publish / 아이콘 보류 / semantic alias light layer)
- design 결정(어떤 색을 어디에 왜)의 SSOT:
cleared-spec/ux-design-specification.md§Visual Design Foundation
License
UNLICENSED (proprietary · mathpresso 내부 사용 우선).