rati 디자인 가이드

이 공간이 설명하는 방식

한 글은 하나의 질문에서 시작합니다. 먼저 짧게 답하고, 이어서 왜 그렇게 동작하는지를 살펴봅니다. 예시 코드와 시각화는 본문의 흐름을 끊는 장식이 아니라 이해를 확인하는 도구입니다.

입문자는 개요부터 읽고, 이미 익숙한 개발자는 원리와 트레이드오프로 바로 내려갈 수 있어야 합니다. 그래서 글마다 명확한 소제목, 충분한 여백, 옆에서 따라오는 목차를 사용합니다.

색은 길잡이입니다

넓은 흰 배경과 짙은 글자가 읽기의 기본입니다. 파란색은 현재 위치와 중요한 전환에만 사용합니다. 코드와 도식에는 정보의 종류를 구분하는 보조 색을 더하되, 색상만으로 뜻을 전달하지 않습니다.

글이 편하게 읽히는 크기

제목은 배민 한나는열한살체로 짧고 선명하게, 본문은 한나체 Air로 여유 있게 씁니다. 한 줄이 지나치게 길어지지 않도록 본문 폭은 760px로 제한하고, 본문은 16px / 1.8을 기본으로 합니다.

움직임은 순서를 보여줍니다

시간 순서가 중요한 개념은 한 장의 그림보다 여러 단계로 나누어 보여주는 편이 이해하기 쉽습니다. 아래는 앞으로의 기술 글에 사용할 시각화의 작은 예시입니다. 각 단계를 직접 넘기거나 재생해 보세요.

자동으로 움직이는 도식에는 일시정지와 단계 이동을 제공합니다. 움직임 감소 설정을 사용하는 독자에게는 전환 효과를 줄입니다. 독자가 웹에서 코드를 실행하는 실습 화면은 만들지 않고, 글에 실린 코드를 자신의 환경에서 실행하도록 안내합니다.

코드는 설명의 일부입니다

예제는 복사해 이해할 수 있을 만큼 작게 제시합니다. 코드 바로 앞에는 무엇을 살펴볼지, 뒤에는 어떤 결과를 예상할지 적습니다. 코드 영역은 IntelliJ IDEA의 Darcula 계열 색상과 어두운 배경을 사용합니다.

const response = await fetch('/api/notes');
const notes = await response.json();

console.log(notes.length); // 응답에 담긴 항목 수를 확인한다.

표는 여러 선택지의 차이를 짧게 비교할 때 사용합니다.

구현을 위한 토큰

이 아래는 사이트를 만들고 새 시각화를 추가할 때 참고하는 상세 규칙입니다. 모든 토큰의 실제 값은 사이트 CSS에서 관리하며, 이 글은 그 값을 사람이 읽기 쉬운 형태로 기록합니다.

색상

글자와 여백

상호작용과 접근성

• 이동에는 링크, 상태 변경에는 버튼을 사용합니다. 키보드 포커스는 항상 보이게 합니다.
• 선택·오류·완료 상태는 색과 함께 텍스트 또는 형태로도 표현합니다.
• 도식의 단계 변경은 설명문과 함께 갱신하고, 재생·일시정지·이전·다음 조작을 제공합니다.
• 짧은 전환은 100~250ms에서 시작하고, prefers-reduced-motion일 때 효과를 줄입니다.
• 모바일에서는 본문을 한 열로 보여주고, 조작 요소에 충분한 터치 영역을 확보합니다.

새 글에 시각화 넣기

일반 문장은 MDX로 작성합니다. 단계별 도식이 필요한 경우 JavaScript 컴포넌트를 별도 파일로 만든 다음 글 안에서 불러옵니다. 아래처럼 보이는 위치에서만 실행하도록 지정하면 긴 글의 처음부터 모든 도식 코드를 내려받지 않아도 됩니다.

import RequestFlow from '../../components/articles/RequestFlow.jsx';

요청이 서버를 오가는 과정을 단계별로 살펴봅니다.

<RequestFlow client:visible />

태그는 각 글의 머리말에서 자유롭게 추가하고 삭제합니다. 분야 목록과 태그 탐색은 공개된 글을 기준으로 자동 생성되므로, 글이 늘어날 때 사이트의 목차도 함께 넓어집니다.