디자인 계약 업데이트
Qokit의 공개 Design Token, 컴포넌트 API 및 통합 계약 변경 기록입니다.
디자인 계약 업데이트
2026-10-21 · 스크롤 메뉴의 고정 작업
ActionItem.pinned 은 start 또는 end 를 받아 작업과 ActionMenu.dropdownHeader 를 스크롤 목록 밖에 유지합니다. 키보드 탐색과 선택은 모든 영역을 포함합니다. 포털 호스트는 트리거의 펼침 방향에서 측정한 --qk-menu-available-height 로 높이를 제한할 수 있습니다. pinned 를 지정하지 않으면 기존 메뉴 구조를 유지합니다.
2026-10-17 · 위젯 사용자 정의 진입점
페이지 위젯 사용자 정의는 프로젝트, 콘텐츠 및 대시보드에서 공유되는 헤더 진입점을 사용합니다. CustomizableWidgetLayoutControls은 선택적 customizeButtonRef 및 disabledCustomize을 추가하며, 축소 제어 옵션은 선택 사항입니다. CustomizableWidgetLibrary은 호스트 간에 모바일 기하 구조, 초기 포커스, Escape 키 및 포커스 복구를 공유합니다. 위젯 지속성 및 명령은 여전히 호스트가 소유합니다. 위젯 사용자 정의 통합을 참조하십시오.
2026-10-17 · 관리된 작업대 패널 제어
WorkspaceHeaderPortal은 일치하는 선택적 호스트 대상과 함께 선택적 startControl 및 endControl을 허용합니다. 관리된 파일 뷰는 단일 자산 편집 및 미리보기와 동일한 헤더 패널 슬롯 및 작업 영역 기하 구조를 사용합니다. 기존 호스트는 제목, 상태 및 작업만 계속 제공해도 됩니다. EditorHeader 통합을 참조하십시오.
2026-10-17 · 측정된 에디터 기본값
useWorkspaceResponsiveProfile은 사용 가능한 작업 영역 측정을 위한 선택적 onWidthChange(width)을 추가합니다. useEditorLayout은 이제 구성된 공유 너비 제한을 호스트 저장소에도 적용하며, readEditorLayout은 네 번째 인수로 선택적 제한을 허용합니다. 기존 호출자는 기본값을 유지합니다. Component Integration을 참조하십시오.
2026-09-26 · Creator · 스타일 구성
세부 간격 · v3: site.theme.spacingOverrides 按 desktop/tablet/mobile → sectionPadding (0–240px), pageGutter, cardGap (0–96px). --qk-site-custom-{sectionPadding|pageGutter|cardGap}-{desktop|tablet|mobile}. 980px / 720px.
버튼 및 링크: primaryButtonStyle, secondaryButtonStyle (solid/outline), buttonFontSize (12–24px), linkUnderline (always/hover/none), linkHoverStyle (none/tint). --qk-site-{primary|secondary}-button-{background|color|border|shadow}, --qk-site-button-font-size, --qk-site-button-size-{sm|md|lg}, --qk-site-link-decoration, --qk-site-link-hover-decoration, --qk-site-link-hover-background. initial → 자동.
고급 색상: mutedColor, borderColor, buttonTextColor, cardSurfaceColor 与对应 dark* 字段 (--qk-site-color-card-rgb).
2026-09-09 · 전역 탐색 단축키
SidebarNavigation / WorkspaceNavigationMenu: 전역 탐색은 Mac에서 Command+\, Windows/Linux에서 Control+\를 사용하며 Creator 안에서도 독립적으로 작동합니다. T와 Shift+T는 편집기 레이아웃 동작을 유지합니다. 편집 가능한 대상, 문자 조합 중인 입력, 반복 및 이미 처리된 이벤트는 무시합니다.
2026-09-08 · EmptyState
프로젝트와 CMS 글/상품 생성 안내는 중앙 정렬, 투명 배경, 간결한 글자 계층과 줄바꿈 작업을 갖춘 EmptyState를 공유합니다. icon, layout, style, description은 선택 사항입니다. 제목은 h2를 사용합니다. 사용자 정의 strong 선택자는 title skin 슬롯으로 이전하세요. 여러 작업은 공통 컨테이너를 사용하며 권한과 생성 처리는 호스트가 담당합니다.
2026-09-08 · SidebarNavigation
SidebarNavigation은 마우스가 180밀리초 머물거나 키보드 포커스를 받으면 동일 출처 경로를 미리 가져옵니다. 고정 및 팝업 탐색은 30초당 최대 8개 대상을 공유합니다. 오프라인, 숨겨진 탭, Save-Data 또는 2G에서는 중단하며 다운로드, 비활성 링크, 새 창 및 같은 페이지 앵커는 제외합니다. 탐색과 저장하지 않은 변경 보호는 유지됩니다.
2026-09-08 - Primary button foreground
알약 모양의 기본 버튼은 Logo 파랑 #4695D8을 유지하며 밝고 어두운 테마 모두 글자, 아이콘, 로딩 표시기를 흰색으로 표시합니다. 마우스를 올렸을 때 약간 밝아지는 효과를 유지합니다. 보조 버튼과 위험 작업은 각 의미에 맞는 색상을 유지합니다.
2026-09-07 - AccountDropdown / SidebarProfile
AccountDropdown에 선택적 compact와 preferences를 추가했습니다. 간결한 모드는 식별자와 제작 기록을 숨기며 기본값은 기존 내용을 유지합니다. 계정 메뉴의 Appearance와 Language는 triggerRole="menuitem"을 지원합니다. 키보드 탐색은 포커스를 복원하고 중첩된 언어 대화상자가 Esc를 직접 처리합니다. SidebarNavigation.searchEnabled의 기본값은 true이며 짧고 고정된 탐색에는 false를 사용할 수 있습니다. 메뉴 없이 href를 갖는 SidebarProfile은 펼침 및 아이콘 모드에서 같은 대상을 엽니다.
2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace
양식의 글자 크기를 통일하고 긴 문구를 줄바꿈하며 알약 모양과 브랜드 색상을 유지합니다. FormField는 그룹 이름을 제공하고 controlId와 내부 입력 id로 레이블을 연결합니다. SearchField는 지운 뒤 초점을 돌려줍니다. Segmented와 ControlMenu는 비활성 옵션을 지원하며 비활성 ActionMenu 항목은 링크가 없습니다. 처리 중인 버튼은 크기와 표시기를 유지합니다. AdminEntityDialog는 필수 항목, 이메일과 JSON을 검증하고 오류에 초점을 맞추며 중복 저장을 막고 실패 시 입력을 유지합니다. EditorWorkspace의 ref.focusControl(element)는 숨겨진 패널을 표시한 뒤 초점을 맞춥니다. 동작 줄이기는 컨트롤 전환을 끕니다. WorkspaceDialog는 제목과 작업을 표시한 채 긴 내용만 스크롤하며 모바일의 짧은 대화 상자는 내용 높이에 맞춥니다。
2026-09-07 · WorkspaceLocationSync / ProjectSwitcher
경로 전환이 완료되면 WorkspaceLocationSync가 임시 공간 선택 패널을 닫고 대상 페이지의 도구를 표시합니다. 검색 및 섹션 설정은 유지됩니다. 사이드바의 범위 이름과 맥락은 별도 줄에 표시하며, 헤더의 긴 이름은 버튼 안에서 줄임표로 표시합니다.
2026-09-07 · 통합 탐색과 Qokit의 둥근 표면
WorkspaceNavigationDock은 items, fallback, className, onClickCapture로 호스트의 탐색과 권한을 재사용하며 별도 세션을 불러오지 않습니다. 펼침·아이콘·숨김 설정을 공유하고 860px 이하에서는 서랍 메뉴를 사용합니다. PlatformHeader.leadingContext는 EditorHeader에도 표시됩니다. 캡슐 버튼과 둥근 표면은 유지하고 중복 테두리를 제거합니다.
데스크톱에서 메뉴를 클릭하면 사이드바를 완전히 숨기거나 마지막 표시 모드로 복원합니다. 메뉴 또는 사이드바 가장자리를 드래그하면 숨김, 아이콘만 표시, 펼침 상태로 전환됩니다. 왼쪽/오른쪽 화살표 키는 읽기 방향을 따릅니다. 드래그를 취소하면 저장된 설정이 유지되며, 모바일에서는 탐색 서랍을 사용합니다.
Next 레이아웃의 Suspense 아래에 WorkspaceLocationSync를 한 번 배치합니다. useWorkspaceQueryState(key, defaultValue, validate)는 [value, setValue, ready]를 반환하며 useWorkspaceQueryRecord(key, defaults, validators)는 선언된 평면 필터만 복원합니다. 인증 정보나 초안을 URL에 저장하지 마세요. WorkspacePage는 제한된 세션 스크롤 위치를 복원하고 내부 영역은 data-workspace-scroll-region과 WorkspaceScrollRestoration을 사용합니다. 취소 가능한 브라우저 뒤로·앞으로 탐색은 기록 추가 없이 이탈 보호를 사용합니다. AdminEntityDialog는 저장 실패와 부모 재렌더링 후에도 입력을 유지하며 버전과 저장 결과는 호스트가 관리합니다.
관리 화면은 페이지 제목 20px/650, 구역 제목 16px/600, 본문과 탐색 14px, 라벨 13px, 보조 설명 12px를 사용합니다. --qk-workspace-body-ink와 --qk-workspace-active-ink는 기존 플랫폼 색상에서 파생됩니다.
알약 모양의 기본 버튼은 --accent-action을 통해 Logo 파랑 #4695D8을 그대로 사용하며 어두운 그라데이션을 제거합니다. 마우스를 올리면 흰색을 8% 섞어 밝힙니다. 글자는 브랜드 잉크색에 검정을 10% 섞어 가독성을 유지합니다. 탐색 강조는 같은 브랜드 파랑과 테마별 글자색을 유지합니다.
드롭다운과 작업 공간 전환기는 --menu-option-font-size (14px), --menu-option-font-weight (500), 줄 높이 1.45를 공유합니다. 선택 항목은 굵기 600, 보조 정보는 12px/400을 사용합니다. WorkspaceNavigationDock은 마우스 호버나 키보드 포커스 시 동일 출처의 목적지를 미리 불러오며 중복 기록 수를 제한합니다. 기존 이탈 보호와 호스트 경로는 유지됩니다.
2026-09-07 - ColumnLayout
ColumnLayout은 고정 탐색 영역, 독립적인 콘텐츠 스크롤 영역, 상단에 유지되는 페이지 도구 모음으로 데스크톱 관리 화면을 채웁니다. WorkspacePage는 평평한 구역과 공통 모서리 Token을 사용합니다. 860px 이하에서는 탐색 서랍을 유지하며 닫힌 서랍은 조작할 수 없습니다. 속성과 업무 동작은 그대로입니다. 중복된 바깥 여백을 제거하고 읽기 너비는 양식 안에서 제한하세요.
2026-09-05 · WorkspaceNavigationMenu / WorkspacePageHeader
로그인한 작업 공간은 PlatformHeader.workspaceActions로 모든 화면 너비에서 계정 및 탐색 영역을 공유합니다. WorkspacePageHeader는 제목과 작업을 통일합니다. WorkspaceNavigationMenu는 권한과 맥락을 유지한 현재 사이드바를 표시하며 EditorNavigationMenu는 호환 별칭으로 남습니다. Studio는 전용 도구 모음을 유지합니다. 공개 페이지 헤더의 표현은 유지됩니다.
WorkspaceNavigationGuard는 dirty, busy, error와 선택적 onSave로 전역 탐색을 보호합니다. 저장 성공이 확인되어 true를 반환해야 이동하며 실패하면 초안을 유지합니다. Language.onBeforeChange(apply)로 언어 변경에도 같은 보호를 적용할 수 있습니다. 저장 중에는 양식 필드를 비활성화합니다.
2026-09-05 · EditorNavigationMenu
EditorNavigationMenu는 호스트의 전체 SidebarNavigation을 겹쳐 표시하여 캔버스를 이동하지 않고 권한과 프로젝트 정보를 유지합니다. 언어와 테마는 하단에 배치하며 하위 메뉴가 Escape를 먼저 처리합니다. 1120px 이하에서는 헤더를 두 줄로 표시하고 메뉴에 현재 보기 이름을 표시합니다. 집중 모드와 브라우저 전체 화면은 독립적입니다. 이동은 진행 중인 저장을 기다리고 초안을 보호합니다.
2026-09-05 · EditorHeader
EditorHeader는 활성 편집기에 호스트의 로고, 계정 및 전역 메뉴를 유지합니다. startControl과 endControl은 양쪽 패널, center는 보기 명령, actions는 저장 작업을 배치합니다. PlatformHeader.editorActions는 반응형 탐색, 언어 및 테마 컨트롤을 재사용합니다. onNavigate는 콜백을 실행하기 전에 저장하지 않은 변경 사항을 처리해야 합니다. 좁은 화면에서는 헤더가 두 줄로 표시되며 하위 메뉴가 Escape를 먼저 처리합니다.
2026-09-05 · SidebarToggleSlot
SidebarToggleSlot은 기존 사이드바 전환 버튼을 작업 공간 헤더에 배치합니다. 왼쪽 사이드바와 슬롯을 하나씩 사용합니다. 상태, 단축키, 모바일 서랍은 계속 SidebarNavigation이 관리하며 슬롯이 없으면 기존 위치를 유지합니다. 모바일 서랍도 헤더 버튼으로 닫으며, 닫은 후 같은 버튼으로 포커스가 돌아갑니다.
2026-09-05 · EditorWorkspace / Dialog / Segmented
view / onViewChange는 본문 편집기를 교체하지 않고 edit, focus, preview를 전환합니다. preview는 미리 보기를 제공하고 previewPanel은 기존 패널을 재사용합니다. layout은 writing, structure, canvas를 지원합니다. storageKey는 패널 너비와 접힘 설정만 기억하며 본문을 저장하지 않습니다.
onSaveAndClose는 저장 성공 확인 후 true, 실패 시 false, 호스트가 이동한 경우 handled, 업무 검증에 사용자 결정이 필요한 경우 pending을 반환합니다. 실패하면 편집기를 유지합니다. closeBehavior="collapse"는 호스트가 초안을 보관할 때만 사용합니다. EditorSaveStatus는 확인된 상태를 표시합니다. EditorViewControls, EditorLeaveDialog, useEditorLayout도 기존 작업 공간에 조합할 수 있습니다.
키보드 변경: Segmented는 Tab 정지점 하나를 사용하며 방향키 / Home / End로 선택합니다. Dialog는 하위 오버레이의 Escape 처리를 존중합니다. 그다음 편집기는 집중 또는 미리 보기를 종료한 뒤 닫기를 처리합니다. LivePreviewToolbar.exitControl은 공통 보기 컨트롤을 받습니다. 저장, 게시, 권한은 계속 호스트가 관리합니다.
2026-09 · EditorWorkspace
EditorWorkspace는 전체 화면 대화 상자, 포커스 관리, 반응형 패널을 제공합니다. dirty는 변경 사항을 버릴지 확인하고, busy는 저장 중 닫기를 막으며, onSave는 Ctrl/Cmd+S를 처리합니다. 권한, 데이터, 저장 및 게시는 호스트 앱이 담당합니다.
2026-08 · 컴팩트 지표 밀도
- 고밀도 운영 워크스페이스를 위해
MetricCard에 선택적density="compact"API를 추가했습니다. - 기존 기본 밀도와 DOM 시맨틱은 변경 없이 유지합니다.
- 컴팩트한 패딩, 수치 스케일 및 최소 높이를 공유 컴포넌트 스타일로 통합하여 라우트에서 시각적 재정의가 필요하지 않습니다.
2026-07 · 통합 폼 컨트롤
@qokit/components/ui에FormField,Input,Textarea,Checkbox,RadioGroup및Switch를 추가했습니다.- 공유
FormField스켈레톤을 통해 라벨, 설명, 오류, 필수 상태 및 ARIA 참조를 연결합니다. Input,Textarea,Select및SearchField를 40px, 44px, 48px 크기와 공유 인터랙션 토큰으로 통합했습니다.- 새로운 폼 기본 컴포넌트를 위해 플랫폼, Admin 및 생성 사이트 Skin 레시피를 추가했습니다.
- 기존
.qk-field스타일은 하위 호환성을 위한 마이그레이션 경로로 유지합니다.
2026-07 · 버튼 크기 타이포그래피
--button-font-size-sm,--button-font-size-md,--button-font-size-lg세 가지 의미론적 Token 추가;Button의sm,md,lg는 이제 각각 14px, 15px, 16px 텍스트를 고정적으로 사용하며, Header, Dialog 또는 페이지 컨테이너의 글꼴 크기를 상속받지 않습니다;- 사이트 Skin에서 버튼 타이포그래피를 조정해야 하는 경우, 해당 의미론적 Token을 덮어쓰고
font-size를 라우팅 class로 재정의하지 마십시오.
2026-07 · 플랫폼 공용 내비게이션 스켈레톤
- 로그인 의존성이 없는
PlatformHeader추가, 플랫폼과 문서 사이트가 동일한 의미론적 스켈레톤을 공유합니다; PublicPlatformHeader및buildPublicHeaderNavItems추가, 플랫폼 익명 상태와 문서 사이트가 동일한 공용 Header 조합 및 내비게이션 구성을 공유합니다;HeaderNavItem에menu유형 추가, 데스크탑 Header는 닫을 수 있는 드롭다운 메뉴를 사용하고 모바일 Header는 자동으로 링크 그룹으로 확장됩니다;SiteFooter에 선택적brandHref및controls추가, 공개 문서 등 다양한 통합 시나리오 지원;PublicPlatformFooter추가, 플랫폼과 문서 사이트가 동일한 Footer Shell을 공유하며 도메인 간 플랫폼 링크 해석 허용;- 위 모든 항목은 하위 호환 가능한 선택적 API이며, 기존 플랫폼 Header 상태 로직과 Footer 기본 컨트롤은 유지됩니다.
2026-07 · 공개 디자인 가이드
- 공개 디자인 계약과 내부 AI 구현 규범 분리;
- 공개 시각적 Token, 컴포넌트 가져오기, Skeleton/Skin 경계, Button, Card 및 접근성 요구사항 명시;
- 파괴적 컴포넌트 변경에는 반드시 마이그레이션 설명 제공;
- 공개 검색, Sitemap 및 LLM 출력은 외부 의존성만 포함;
호환성 설명
-
추가된 선택적 속성, 선택적 Skin 슬롯 및 의미론적 Token은 일반적으로 하위 호환성을 유지합니다;
-
속성 삭제 또는 이름 변경, 기본 DOM/의미론적/키보드 동작 변경은 파괴적 변경으로 간주됩니다;
-
파괴적 변경은 이 페이지에서 영향 범위, 대체 API 및 마이그레이션 단계를 설명합니다.
-
2026-09-06: 데스크톱 탐색은 펼침과 아이콘 모드를 유지하며 자동 숨기기를 추가합니다. SidebarNavigation / WorkspaceNavigationMenu / Dialog
-
2026-09-06: EditorViewControls는 편집/집중 모드와 기본 전체 화면을 별도로 제어합니다. EditorViewControls
-
2026-09-06:
Language와Appearance variant="menu"는 레이블, 현재 값, 화살표를 표시하는layout="row"를 지원합니다. 기본 간결한 레이아웃과 언어 변경 보호는 유지됩니다.SiteHeaderCopy.helpResources와contactSupport로 작업 공간 도움말 링크 이름을 선택적으로 지정합니다. Language / Appearance -
2026-09-06: 사이드바 페이지에서 중복 헤더 메뉴 버튼을 제거하고 기존 전환 버튼과 탐색 API를 유지합니다. WorkspaceNavigation
-
2026-09-06: 전역 탐색에는 메뉴 아이콘을, 편집 도구에는 좌우 패널 아이콘을 사용합니다. WorkspacePanelReveal / EditorViewControls
-
2026-09-06: 보기 모드 ·
E/T/V/F·Segment.shortcut. EditorViewControls -
2026-09-06:
PlatformHeader.workspaceNavigation은 전역 탐색을 로고 앞에 배치합니다 PlatformHeader.workspaceNavigation
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview는 center만 테두리 없는 간결한 미리보기 도구 모음으로 표시합니다. 로고, 계정, 저장, 패널 컨트롤은 마운트된 채 숨겨집니다. 별도의 LivePreviewToolbar를 쓰면 편집기 헤더를 숨기고 EditorViewControls.returnView(edit 또는 focus)로 이전 모드를 복원합니다. 접근 가능한 돌아가기와 독립적인 전체 화면 조작을 유지하며 사이트 자체의 헤더는 표시합니다.
2026-09-06 · Builder / CMS
Builder와 CMS는 패널, 삽입 그림, 표시 설정에 BuilderWorkspace, EditorCatalog, EditorComponentSettings를 함께 사용합니다. 프리셋은 관련 설정을 한 번에 적용하고 기존 콘텐츠를 보존하며, 저장과 실행 취소는 각 호스트가 담당합니다. 작업 영역 컨트롤은 플랫폼 테마를, 콘텐츠는 사이트 테마를 따릅니다.
2026-09-06 - EditorViewControls
하나의 버튼으로 양방향 전환합니다. 편집 중에는 집중, 집중 중에는 편집을 표시합니다. 클릭하거나 T를 누르며, E는 바로 편집으로 돌아갑니다. 좁은 헤더에서도 전환 버튼은 유지하고 미리 보기, 전체 화면과 추가 작업은 더 보기 메뉴에 둡니다. EditorViewControls
2026-09 · 관리 작업 공간
좁은 WorkspaceDataTable과 AdminDataTable은 선택, 사용자 지정 머리글, 작업을 유지하는 레이블 기반 레코드를 기본 표시합니다. 비교 표에는 mobileLayout="scroll"을 사용합니다. WorkspaceFilterToolbar는 검색과 필터 뒤에 정렬과 보기 제어를 배치합니다. 사이드바는 h2, 페이지는 h1을 사용합니다.
2026-09-08 · Task focus
useSidebarTaskFocus(active)는 집중 작업 중 탐색 메뉴를 일시적으로 숨깁니다. 종료 시 이전 표시 방식으로 복원하되 사용자가 직접 변경한 모드를 우선합니다. 자동 숨김은 저장된 설정을 변경하지 않습니다.
추가 API 참조 (영어, 번역 예정)
Optional FloatingToolPanel.viewKey animates tool changes without remounting the body. Shared opening, closing, unfolding and pin feedback respect reduced motion; pointer geometry updates run at most once per animation frame. Closed Dialog keepMounted surfaces become inert and hidden from assistive technology immediately, including during an exit transition. Existing props and document state ownership are unchanged.
The opt-in useWorkspacePanelEdgeDrag hook connects existing workspace borders to expanded, icon and hidden states in one mouse or touch gesture, with keyboard resizing, RTL and cancellation. ResizablePanels now marks its separators with data-workspace-panel-edge; existing hosts retain their behavior until they enable the hook. Hosts own widths, state, focus and visual skins. See the integration contract.
추가 API 참조 (영어, 번역 예정) · 2026-10
2026-10-08 · Workspace title navigation
WorkspaceLayout and WorkspacePageHeader accept optional backControl before the title. Use WorkspaceBackButton with a localized label and the existing href or onClick; it supplies an icon, accessible name, Tooltip and RTL mirroring. Hosts retain return destinations, list state and navigation guards. Existing headers without this slot keep their layout.