Design System Specification (nhivo.io.vn)

This document outlines the visual design system, token configuration, and component styling patterns used across the platform. It is designed to be reusable and applicable to sister sites (such as the Vietnam Wedding Guide blog) to ensure consistent, premium editorial presentation.

1. Core Visual Philosophy

Quiet Restraint: Minimal visual decoration, using typography, whitespace, and structural rhythm rather than graphic assets to establish authority.
Editorial Experience: High-end editorial print feel adapted for the web. Visually lightweight, text-first, and highly readable.
Calm Transitions: Micro-interactions and transitions should feel silent, deliberate, and invisible, avoiding snappy or flashy animations.

2. Design Tokens & Variables

Color Palette (Tailwind Tokens)

The palette mimics natural materials (paper, ink, terracotta) and uses custom HSL variables to support a cohesive theme switch between light and dark modes.

Variable Name	Utility Class	Light Hex / Fallback	Dark Hex / Fallback	Usage
`paper`	`bg-paper`	`#F4F1E2`	(Dynamic inverted)	Primary background canvas
`paper-alt`	`bg-paper-alt`	`#EAE6D6`	(Dynamic inverted)	Card backgrounds, alternative rows
`ink`	`text-ink`	`#513229`	`#e2e8f0` (slate)	Primary body copy, headers
`ink-secondary`	`text-ink-secondary`	`#786059`	`#94a3b8`	Supporting text, metadata
`terracotta`	`text-terracotta`	`#C98E73`	`#C98E73`	Accent highlights, buttons
`border-light`	`border-border-light`	`#DDDABF`	`#475569`	Subtle line dividers, borders

For dynamic primary and highlight colors, configure tailwind variables mapping to rgb(var(--color-primary-50) / <alpha-value>) etc. in tailwind.config.mjs.

3. Typography & Hierarchy

Typography defines the grid and reading order. Default browser styles are bypassed entirely.

Font Families

Heading: Serif or high-character sans (configured via siteConfig.fonts.families.heading). Used for h1 through h6.
Body & Prose: Premium highly legible sans (e.g. Inter, Outfits) with a font-feature-setting of "rlig" 1, "calt" 1.

Sizing and Spacing

Body text: Optimized for long-form reading (line-height: 1.7).
Heading Scroll Margin: Set scroll-margin-top: 2rem to prevent overlapping floating navbars during jump links.
Markdown Rendering: Leverages @tailwindcss/typography (.prose class) with a clean container width limit.

4. Layout & Grid System

Width Constraints

Different viewport configurations dictate content density depending on the page type:

Index/Gallery Layouts: Maximum width 1000px (max-w-[1000px]) centered (mx-auto). This allows a grid layout (e.g., 2-column or 3-column) to breathe.
Article/Reading Layouts: Maximum width 720px (max-w-[720px]) centered. This is the optimal line length (60–75 characters per line) for long-form editorial reading.
Whitespace Rhythm: Large vertical gaps (e.g., py-16 or py-24 on desktop) are used to isolate content sections, encouraging progressive disclosure.

5. UI Primitives & Components (Radix UI)

Headless components from Radix UI provide interactive behavior, styled cleanly with Tailwind utility classes.

Accessibility State Design

Interactive elements must explicitly handle the following tailwind-state combinations: - Focus: focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-terracotta - Active / Select: data-[state=open]:bg-paper-alt (for dropdown menus/popovers) or selection background highlights. - Hover: Subtle opacity transitions (transition-opacity hover:opacity-80 or color shifting).

Reusable Primitives Structure

Dropdown Menus / Selects:
Renders in Portal wrapper to avoid parent overflow: hidden constraints.
Styled drop-shadow container (shadow-lg).
Modals (Dialogs):
Fixed, centered content (left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2).
Semi-transparent dark overlay backdrop (bg-black/50 backdrop-blur-sm).
Keyboard trapping is preserved.

6. Motion & Animation System

The motion system is calibrated to feel invisible and slow. Avoid springy, high-frequency, or bounce transitions.

Predefined Keyframes (`tailwind.config.mjs` tokens):

Fade In: animate-fade-in (Duration: 0.2s ease-in-out)
Slide Up: animate-slide-up (Duration: 0.3s ease-out with a subtle 10px translate offset)
Scale In: animate-scale-in (Duration: 0.2s ease-out with scale from 95% to 100%)

7. Custom CSS Implementations

For custom features or overrides (such as KaTeX formatting or custom scrollbar overrides), stick to utility-aligned classes in global.css:

/* Custom utility override pattern */
.scrollbar-hide {
  -ms-overflow-style: none;
  scrollbar-width: none;
}
.scrollbar-hide::-webkit-scrollbar {
  display: none;
}