Start with shadcn/ui components, then shape them into your product in
DESIGN.md. This repository contains a Google Stitch-compatible guide for
clear, comfortable product interfaces. Update Korean DESIGN.md first, then
keep the English, Japanese, and Simplified Chinese editions aligned.
The system combines warm neutral surfaces, one restrained blue action color, Geist and Geist Mono typography, open spacing, clear containment, natural motion, and inclusive defaults. The components remain familiar while the tokens, states, and page composition give the interface its own character.
Explore Comfort DESIGN.md as a live, responsive reference:
The site maps the tokens into light and dark themes, responsive specimens, and detailed reference pages:
- Principles: Natural, Certain, Meaningful, and Growing, adapted to Comfort's product language.
- Foundations: all 15 SEED-inspired semantic Foundations, adapted to Comfort's tokens and product language.
The component catalog is intentionally not published while its structure and examples are being redesigned. The shadcn source components remain available to the site itself without presenting the previous catalog as finished guidance.
The documentation shell uses a floating header with a persistent 24px top gap,
contextual rails without vertical separators, an on-page outline, previous/next
navigation, a distributed sitemap, and a clipped Comfort DESIGN.md footer
signature. Its content, token language, visual system, and examples are original
to Comfort.
The reference site uses Vite 8, React 19, TypeScript 6, Tailwind CSS 4, and
shadcn components with Radix UI and Base UI primitives.
Component source lives in src/components/ui; Comfort-specific composition
and guidance live in the page and shell layers.
Static route copies are generated at build time so every documentation URL loads directly on GitHub Pages without a client-side redirect.
Use Node.js 22 or later:
npm ci
npm run devRun the full local gate before publishing:
npm run validateThe command verifies the 15-Foundation catalog and four DESIGN.md editions, then runs ESLint, TypeScript, the production Vite build, 72-route generation, and static site verification.
- 한국어: DESIGN.md
- English: DESIGN.en.md
- 简体中文: DESIGN.cn.md
- 日本語: DESIGN.jp.md
All four files carry the same machine-readable YAML tokens, section order, and
15-Foundation inventory. The live site defaults to English at /; Korean is
available at /ko/, Japanese at /jp/, and Chinese at /cn/.
Each document has two layers:
- YAML front matter with exact colors, typography, radii, spacing, and component tokens.
- Markdown rationale in the maintained order:
Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Foundations → Components → Do's and Don'ts → Responsive Behavior → Interaction & Motion → Accessibility & Responsible UX → State & Feedback → Content & Localization → Implementation Guide → Verification → Iteration Guide → Known Gaps → References.
Use YAML for exact token values and the prose for intent, hierarchy, interaction, and delivery behavior.
Give DESIGN.md to a coding or design agent before UI work:
Read DESIGN.md, apply its theme tokens and component guidance, and preserve its
interaction, accessibility, responsive, and verification requirements.
Map YAML roles to the consuming application's CSS variables or theme configuration once. Components should consume semantic roles instead of repeating raw colors, radii, or spacing values.
Use Google's official linter:
npx @google/design.md lint DESIGN.md
npx @google/design.md lint DESIGN.en.md
npx @google/design.md lint DESIGN.cn.md
npx @google/design.md lint DESIGN.jp.mdThe documents are expected to produce no errors or warnings. The informational token summary is normal.