Button 버튼
Button과 IconButton의 시맨틱, 크기, 모양, 상태 및 접근성 규격.
AI 버튼은 버튼의 크기와 의미를 재사용하면서도 독특하고 인지 가능한 Qokit AI 상태를 추가합니다.
AI 버튼을 선택하여 작업 상태를 미리보기하세요.
Qokit 버튼 컴포넌트 규격
이 문서는 Qokit 플랫폼, Builder, CMS, Dashboard, Admin, 마케팅 페이지 및 생성된 사이트에서의 버튼 사용 규칙을 정의합니다. 목표는 버튼의 컴포넌트, 시맨틱, 모양, 크기, 아이콘, 상태 및 접근성을 통일하여 각 라우트에서 로컬 CSS로 버튼을 재설계하는 것을 방지하는 것입니다.
1. 핵심 모델
버튼은 단순히 "타원형, 원형"으로 분류되는 것이 아니라, 서로 독립적인 다섯 가지 차원으로 구성됩니다:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- 컴포넌트 유형은 버튼에 표시되는 텍스트가 있는지, 그리고 정사각형 클릭 영역을 유지해야 하는지를 결정합니다.
- 시맨틱 우선순위는 현재 작업에서 버튼의 우선순위와 색상을 결정합니다.
- 크기는 안정적 높이, 텍스트 글꼴 크기 및 터치 영역을 결정합니다.
- 모양은 모서리 둥글기만 결정하며, 우선순위나 비즈니스 시맨틱을 표현하지 않습니다.
- 공간 계층은 컨트롤이 현재 평면에서 떠 있는지 여부만 나타내며, 작업 시맨틱을 변경하지 않습니다.
새로운 클래스 이름 조합으로 새로운 버튼 유형을 만들지 마십시오. 먼저 공유 컴포넌트의 기존 속성에서 선택하십시오.
2. 컴포넌트 선택
Button
표시되는 텍스트가 있는 모든 작업에 사용됩니다. 포함:
- 순수 텍스트 버튼;
- 텍스트 앞에 아이콘이 있는 버튼;
- 텍스트 뒤에 아이콘이 있는 버튼;
- 버튼처럼 보이는 페이지 링크.
플랫폼의 Button은 기본적으로 완전 둥근 pill을 사용하며, 시각적으로 타원형입니다. 버튼에 표시되는 텍스트가 포함되는 한, 원형 아이콘 버튼으로 변경해서는 안 됩니다.
variant은 그림자와 분리됩니다: primary은 기본적으로 raised을 사용하고, secondary, danger, ghost는 기본적으로 flat를 사용합니다. 목록 행, 카드 내부, 툴바 및 복합 캡슐 내부 작업은 반드시 flat이어야 합니다; 독립적 주요 작업은 raised을 사용할 수 있습니다; 콘텐츠 위에 떠 있는 작업만 floating을 사용합니다. 독립 캡슐 또는 세그먼트 컨트롤은 가장 바깥쪽에서만 한 번 그림자를 그리며, 라우트는 로컬 CSS로 공유 계층을 재작성해서는 안 됩니다.
import { Button } from '@qokit/components/ui';
<Button type="button" variant="primary">
保存
</Button>
<Button
leadingIcon={<SaveIcon aria-hidden="true" />}
type="button"
variant="primary"
>
保存
</Button>
<Button
href="/projects"
trailingIcon={<ArrowRightIcon aria-hidden="true" />}
variant="secondary"
>
查看项目
</Button>IconButton
아이콘만 있고 표시되는 텍스트가 없는 간결한 도구 작업에 사용됩니다. 예: 닫기, 더 보기, 뒤로, 메뉴 전환 또는 삭제.
IconButton은 모든 크기에서 동일한 너비, 동일한 높이 및 완전 둥글기를 유지하므로 시각적으로 원형 버튼입니다. 기본적으로 ghost을 사용하며, 유형 수준에서 aria-label를 강제합니다.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>규칙:
- 아이콘 자체는
aria-hidden="true"을 사용하고, 버튼 이름은aria-label에서 제공합니다. - 익숙하지 않거나 의미가 불분명할 수 있는 아이콘은 공유
Tooltip를 함께 사용해야 합니다; tooltip은aria-label을 대체할 수 없습니다. - DOM
title속성을 제품 힌트로 사용하지 말고,tooltip을 설정하면서 수동으로 Tooltip을 감싸지도 마십시오. - Tooltip은 읽기 전용 정보 레이어이며, 타원형 버튼이 아닙니다. 공유 컴팩트 Tooltip 모서리 둥글기를 사용하며,
pill, 버튼 hover, pressed 또는 focus 시각 효과를 재사용해서는 안 됩니다. - 빈 텍스트, 숨겨진 텍스트 또는 고정 너비의
Button으로IconButton을 모방하지 마십시오. IconButton에shape을 설정하지 마십시오; 원형은 해당 컴포넌트 계약입니다.
Button을 사용해서는 안 되는 시나리오
- 탭은 Tabs/PillTabs/Segmented 등 해당 컴포넌트를 사용합니다.
- 메뉴 항목은 Menu/ActionMenu 해당 컴포넌트를 사용합니다.
- 상태, 레이블 및 필터 결과는 Pill 또는 상태 컴포넌트를 사용합니다.
- 일반 텍스트 내비게이션은 시맨틱 링크를 사용합니다; 버튼 수준의 시각적 강조가 필요한 경우에만
href가 포함된Button을 사용합니다.
3. 시맨틱 계층 variant
| Variant | 의미 | 일반적 시나리오 | 사용 제한 |
|---|---|---|---|
primary | 현재 영역의 주요 작업 | 저장, 게시, 생성, 지금 체험 | 하나의 작업 영역에는 일반적으로 하나의 주요 작업만 유지 |
secondary | 명확하지만 차순위 작업 | 미리보기, 취소, 뒤로, 가져오기 | 주요 작업과 시각적 주의를 경쟁해서는 안 됨 |
ghost | 낮은 강조, 컨텍스트 도구 작업 | 닫기, 더 보기, 툴바 작업, 가벼운 뒤로 | 기본적으로 투명, 유일한 핵심 CTA가 될 수 없음 |
danger | 삭제하거나 상당한 손상을 초래하는 작업 | 항목 삭제, 콘텐츠 제거, 데이터 비우기 | 파괴적 시맨틱만 표현하며, 일반 강조 색상으로 사용하지 않음 |
variant은 시맨틱과 시각적 계층을 표현하며, 모양이 아닙니다. 예를 들어 ghost은 텍스트가 있는 타원형 버튼일 수도 있고, 원형 IconButton일 수도 있습니다.
선택 순서:
- 현재 작업에서 유일하게 가장 중요한 다음 단계를 찾아
primary로 설정합니다. - 여전히 명확하게 보여야 하는 보조 작업은
secondary을 사용합니다. - 툴바 또는 컨텍스트의 낮은 강조 작업은
ghost을 사용합니다. - 실제 파괴적 작업만
danger을 사용하며, 기존 확인 절차를 따릅니다.
"어떤 색상이 더 예쁜가"에 따라 variant를 선택하지 마십시오.
4. 크기 size
| Size | 높이/지름 | 텍스트 글꼴 크기 | 권장 시나리오 |
|---|---|---|---|
sm | 40px | 14px | 상단 내비게이션, 컴팩트 툴바, 밀집 작업 영역 |
md | 44px | 15px | 기본 폼, CMS, 대화상자 및 일반 작업 |
lg | 48px | 16px | 마케팅 페이지 주요 CTA, 더 강한 터치성이 필요한 주요 작업 |
기본 크기는 md입니다.
- 동일한 버튼 그룹은 동일한 크기를 사용합니다.
- 컴팩트 컨트롤은 40px 미만일 수 없습니다; 모바일 주요 작업은 최소 44px를 우선 사용합니다.
Button의 높이와IconButton의 지름은 동일한 크기 토큰 세트를 사용하므로 동일한 툴바에서 정렬할 수 있습니다;IconButton의 표시 아이콘 크기는 18px로 통일됩니다.Button텍스트 글꼴 크기는 size에 해당하는 공유 토큰에 의해 결정되며, Header, Dialog 또는 기타 부모 컨테이너의 글꼴 크기를 상속하지 않습니다.- 라우트 CSS는 버튼의 배열, 간격 및 필요한 너비를 제어할 수 있지만, 공유 버튼의 높이 또는 글꼴 크기를 재정의할 수 없습니다.
- 텍스트가 길 경우 레이아웃이나 버튼 컨테이너를 조정하는 것을 우선시하며, 높이, 글꼴 또는 좌우 간격을 압축하여 해결하지 마십시오.
5. 모양 shape
| Shape | 표현 | 사용 범위 |
|---|---|---|
pill | 완전 둥글기; 텍스트가 있을 때 타원형 | 플랫폼 기본값, 마케팅 페이지, Dashboard, Builder, CMS 및 Admin에 적합 |
rounded | 12px 모서리 둥글기 | 생성된 사이트 테마에서 명시적으로 작은 모서리 둥글기를 요구할 때만 사용 |
Button 기본값은 shape="pill"입니다. 플랫폼 프론트엔드는 rounded을 명시적으로 설정하지 말고, 로컬 CSS에서 모서리 둥글기를 재정의하지 마십시오.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton은 항상 원형이며, pill / rounded의 비즈니스 선택에 참여하지 않습니다.
6. 아이콘 규칙
- 텍스트 앞 아이콘은
leadingIcon을 사용하고, 텍스트 뒤 아이콘은trailingIcon을 사용합니다. - 하나의 버튼에는 일반적으로 하나의 보조 아이콘만 사용합니다.
- 저장, 추가, 뒤로 등 익숙한 작업은 아이콘으로 인식을 강화할 수 있지만, 아이콘이 핵심 버튼의 표시 텍스트를 대체할 수 없습니다.
- 화살표가 계속, 진입 또는 펼침을 나타낼 때 일반적으로 텍스트 뒤에 위치하며; 뒤로 아이콘은 일반적으로 텍스트 앞에 위치합니다.
children에서 아이콘과 텍스트의 레이아웃을 수동으로 작성하지 마십시오; 컴포넌트가 이미 icon과 label 슬롯을 제공합니다.- 공유 아이콘을 사용하고
currentColor을 상속하며, 라우트 CSS에서 아이콘 색상 또는 크기를 하드코딩하지 마십시오. - 로딩 상태는 버튼의 기존 너비와 높이를 유지하고, 이해하기 쉬운 짧은 텍스트 또는 기존 로딩 피드백을 제공해야 합니다; 텍스트 전환으로 툴바가 흔들리지 않도록 합니다.
7. 버튼과 링크
작업과 내비게이션은 올바른 시맨틱을 사용해야 합니다:
- 제출, 저장, 레이어 열기, 상태 전환 등 현재 페이지 작업은
href이 없는Button를 사용하며, 최종적으로<button>으로 렌더링됩니다. - 다른 라우트 또는 리소스로 이동할 때는
href가 포함된Button를 사용하며, 최종적으로 Next.js<Link>으로 렌더링됩니다. - 폼 내의 비제출 버튼은 반드시
type="button"을 명시적으로 작성해야 합니다; 제출 버튼은type="submit"을 명시적으로 작성합니다. onClick로 일반 페이지 내비게이션을 모방하지 마십시오.
비활성화된 링크는 aria-disabled을 사용하고 Tab 순서에서 제거됩니다; 비활성화된 네이티브 버튼은 disabled을 사용합니다. 비활성화 상태는 투명도 감소만으로 표현할 수 없으며, 비즈니스 로직도 작업을 차단해야 합니다.
8. 상태 및 접근성
공유 컴포넌트는 hover, focus-visible, disabled 및 색상 상태를 통일하여 담당합니다. 비즈니스 코드는 여전히 다음을 충족해야 합니다:
- 일반 미선택 버튼 hover는
--control-surface-hover를 사용하고; 누름, 선택 및 펼침은--control-surface-active을 사용합니다.focus-visible은 중성 표면에서--focus-ring를 유지하며, 라우트 스타일은 hover와 지속 상태를 동일한 옅은 파란색 규칙으로 병합해서는 안 됩니다. - 버튼 이름은 직접적이고 구체적이어야 하며, 어떤 일이 발생할지 설명해야 합니다. 예: "저장", "웹사이트 게시", "항목 삭제".
IconButton은 반드시 현지화된aria-label을 제공해야 합니다.- 장식 아이콘은
aria-hidden="true"을 사용하여 스크린 리더의 중복 낭독을 방지합니다. - 키보드 포커스는 반드시 표시되어야 합니다; 라우트 CSS는 공유 focus ring을 제거해서는 안 됩니다.
- hover를 유일한 힌트로 사용하지 마십시오; 상호작용은 키보드와 터치를 동시에 지원해야 합니다.
- 비활성화 버튼은 사용자가 일시적으로 실행할 수 없는 작업에만 사용됩니다; 이유를 설명해야 하는 경우 근접한 설명이나 tooltip을 제공해야 합니다.
- 오류, 권한 요구, 위험, 비용 및 기타 작업 중요 정보는 반드시 표시되어야 합니다; Tooltip은 정보만 보완할 수 있으며, 이러한 정보를 발견하는 유일한 방법이 될 수 없습니다.
- 비동기 작업은 중복 제출을 방지하고, 이해하기 쉬운 진행 중 피드백을 유지해야 합니다.
- 위험 작업은
danger을 사용하고, 기존 위험 확인 패턴을 재사용합니다; 빨간색에만 의존하여 위험을 전달하지 마십시오. - 중국어 또는 기타 언어의 버튼 텍스트는 이해할 수 없을 정도로 잘려서는 안 됩니다. 긴 텍스트와 모바일 너비를 반드시 검증해야 합니다.
9. 스타일 책임 경계
공유 버튼의 구조, 시맨틱 및 상태는 Button / IconButton이 담당합니다; 시각적 토큰과 공유 CSS는 컴포넌트 패키지가 담당합니다; 라우트는 레이아웃만 담당합니다.
공유 레이어가 담당하는 것
- DOM, 링크/버튼 시맨틱, disabled 동작;
- icon/label 슬롯 및 접근성 유형 제약;
- variant, size, shape 클래스;
- 높이, 모서리 둥글기, 패딩, 글꼴 크기, 글꼴 두께;
- 배경, 텍스트 색상, 그림자, hover, focus-visible 및 disabled 상태.
라우트 레이어가 담당할 수 있는 것
- 버튼 그룹 방향, 간격, 정렬 및 줄바꿈;
- 반응형 배열;
- 특정 워크플로에 필요한
width: 100%또는 컨테이너 너비; - 기본 시각을 변경하지 않는 위치 지정 클래스.
라우트 레이어가 담당해서는 안 되는 것
- 버튼 높이, 글꼴 크기, 모서리 둥글기, 배경, 텍스트 색상, 그림자 또는 focus ring 재작성;
- 하드코딩된 색상 또는
border-radius: 999px으로 공유 버튼 재구현; primary-alt,outline-blue,icon-round등 로컬 시각적 변형 추가;!important으로 공유 버튼 계약과 경쟁;.qk-ui-button의 기본 스타일을 직접 복사.
여러 페이지에서 필요한 새로운 시맨틱 변형이 실제로 나타나는 경우, 먼저 공유 ButtonVariant, 토큰 및 primitives.css에서 통일된 계약을 수립해야 하며, 라우트에서 새로운 스타일을 추가해서는 안 됩니다.
10. API 빠른 참조
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Button의 주요 속성:
| 속성 | 기본값 | 설명 |
|---|---|---|
variant | primary | 시맨틱 및 시각적 계층 |
size | md | 높이, 텍스트 글꼴 크기 및 가로 패딩 |
shape | pill | Button의 모서리 둥글기 모양 |
leadingIcon | 없음 | 텍스트 앞 아이콘 |
trailingIcon | 없음 | 텍스트 뒤 아이콘 |
href | 없음 | 제공 시 링크로 렌더링 |
disabled | false | 상호작용 비활성화 |
tooltip | 없음 | 공유 Tooltip의 보완 콘텐츠; 표시되는 핵심 정보 또는 aria-label을 대체할 수 없음 |
tooltipPlacement | bottom | 선호 방향; 공유 Tooltip는 뷰포트 내에 유지되도록 뒤집힐 수 있음 |
tooltipPortal | true | 클리핑 컨테이너 외부에 렌더링하며 레이아웃 래퍼 레이어 추가 없음 |
skin | 없음 | skeleton/skin 계약에 따라 클래스 슬롯 및 변수 적응 제공 |
IconButton은 적용 가능한 Button 속성을 상속하지만, shape, leadingIcon 또는 trailingIcon를 제공하지 않습니다; aria-label을 요구하며, 기본값은 variant="ghost"입니다.
비즈니스 코드에서 variant과 네이티브 버튼 type을 명시적으로 작성하여, 작업 시맨틱이 코드 리뷰에서 명확하게 보이도록 하는 것이 권장됩니다.
11. 일반 조합
// 主要操作:椭圆形文字按钮
<Button type="submit" variant="primary">
保存
</Button>
// 次要操作
<Button type="button" variant="secondary" onClick={onPreview}>
预览
</Button>
// 低强调文字操作
<Button type="button" variant="ghost" onClick={onCancel}>
取消
</Button>
// 图标 + 文字,仍然使用 Button
<Button
leadingIcon={<PlusIcon aria-hidden="true" />}
type="button"
variant="primary"
>
新建内容
</Button>
// 纯图标:圆形按钮
<IconButton aria-label="更多操作" tooltip="更多操作" type="button">
<MoreIcon aria-hidden="true" />
</IconButton>
// 危险操作
<Button type="button" variant="danger" onClick={openDeleteConfirm}>
删除项目
</Button>12. 리뷰 체크리스트
버튼 관련 UI를 제출하기 전에 확인:
Button또는IconButton을 우선 재사용했는가?- 텍스트 포함 버튼과 순수 아이콘 버튼이 올바른 컴포넌트를 선택했는가?
- 현재 작업 영역에 명확한
primary이 하나만 있는가? secondary,ghost,danger이 색상 선호가 아닌 시맨틱에 따라 사용되었는가?- 플랫폼
Button이 기본pill을 유지하고,IconButton이 원형을 유지하는가? - 각 Tooltip이 여전히 컴팩트 모서리 둥글기의 정보 레이어이며, 클릭 가능한 타원형 버튼처럼 보이지 않는가?
- 브라우저 네이티브
title, CSSdata-tooltip말풍선, 중복 힌트 및 텍스트 버튼의 동의어 Tooltip을 제거했는가? - 크기가
sm,md,lg만 사용되며, 동일 그룹의 높이와 글꼴 크기가 일관된가? - 네이티브 버튼이 올바른
type을 명시적으로 설정했는가? - 아이콘이 중복 스크린 리더 정보를 숨겼으며,
IconButton에 현지화된aria-label이 있는가? - focus-visible, disabled, 비동기 및 위험 확인 상태가 완전한가?
- 라우트 CSS가 레이아웃만 처리하며, 버튼 기본 시각을 재정의하지 않는가?
- 데스크톱 및 모바일 너비에서 긴 텍스트, 터치 크기 및 버튼 그룹 배열을 검증했는가?
13. 구현 출처
- 컴포넌트 API:
packages/components/src/ui/Button/Button.tsx - 컴포넌트 내보내기:
packages/components/src/ui/Button/index.ts - 크기 및 색상 토큰:
packages/components/src/styles/foundations.css - 공유 버튼 스타일:
packages/components/src/styles/primitives.css - 공개 컴포넌트 접근 계약:
docs/public/design/component-integration.md
문서와 구현 간 차이가 있을 경우, 동일한 변경에서 컴포넌트, 토큰, 스타일 및 이 문서를 동기화해야 합니다.