Zillion Design Guide

A little more clarity.

Quiet surfaces. Useful details. One language, in light and dark.

Explore the design rules

Foundations

Color, type, surfaces and spacing.

Soft Precision

Let content lead. Keep the container quiet and the details useful.

Surface

Porcelain in light mode, charcoal in dark. A fine edge and soft depth; no gold outlines.

Shape & space

24px cards · 20px padding · 16px gaps. Nested images use 12px corners; inputs remain 8px.

Typography

14px card content · 12px metadata · 32px key numbers. Sans-serif for UI; serif only for notes and the wordmark.

Composition

One purpose per card. Align headings and footers; vary the interior for lists, images, numbers and notes.

Behavior

160ms feedback, 240ms content replacement. Keep geometry stable; every action has a visible result.

Responsive

Three columns when space allows, two on medium screens, one on mobile. Themes keep identical geometry.

Color

Neutral backgrounds. Gold accents. Separate colors for status.

Canvas--canvas#F7F7F5 / #141517

Surface--surface#FFFFFF / #202123

Ink--ink#222525 / #F2F2EC

Accent--accent#81602D / #DCB87A

Typography

Sans-serif for headings, content and controls. Reserve editorial serif for short notes and the wordmark.

Font preview

Make room for the work.

App UI: Inter / PingFang, 32–12px below. Guide chapter headings: 28px. Brand display: Playfair / Songti; wordmark: Cormorant.

App title--type-title32px / 600 / 1.2

Make room for the work.

Section--type-section24px / 600 / 1.3

Make room for the work.

Reading--type-reading16px / 400 / 1.7

Make room for the work.

Interface--type-ui14px / 500 / 1.5

Make room for the work.

Metadata--type-meta12px / 400 / 1.5

Make room for the work.

Size / weight / line height. Keep Chinese tracking natural; align data with tabular numbers.

Contrast & focus

Text ≥ 4.5:1. Large text and essential control boundaries ≥ 3:1. Check both themes.

Aa 字--ink / --canvas—

Aa 字--muted / --surface—

Aa 字--accent / --canvas—

Aa 字--field-line / --surface—

Field focus: a neutral 2px edge; other controls keep a visible keyboard outline. Status always includes a label. Glass needs a separate check over its actual background.

Surfaces

Quiet solid surfaces. Soft card edges; clear boundaries for inputs.

Content surface

A quiet card on the canvas. Use the same surface in forms, lists and modules.

Nested content · subtle tonal separation

Interactive boundary

Workspace nameFields keep a clear edge. Focus strengthens it without an outer glow.

Space & shape

4px grid · 8px fields · 24px cards · 16px gaps.

4

8

12

16

24

32

48

64

Components

Try the controls below.

Content modules

One shared shell, different content. Try the period selector, inbox, note, images, timer and checklist.

Bodega Bay

Sonoma County, CA

Portfolio

Total value

24,680 USD

Inbox

3 unread

Quick note

Leave room for the unexpected.

Local note · this session

Moodboard

Upcoming event

Today

19:30

Sunset at the coast

Bodega Bay, CA

Activity

This week

3.1 km

M

T

W

T

F

S

A moment of focus

25:00

Project list

2/3

Finalize deck09.12Source materials09.15Plan site visit09.18

Changes stay in this session.

Actions

One primary action per group.

Field states

One primitive across default, filled, invalid, disabled and read-only states. Tab through available fields to compare focus.

DefaultFilledInvalid exampleName is required.DisabledRead-only

Dropdowns

Choose a view to change the module below. Keep the label visible.

Module view

Summary view selected.

Workspace overview

3Modules2Ready

Unavailable

44px minimum height · 16px field text · 8px corners. Arrow keys browse; Enter selects; Escape closes. Searchable comboboxes and action menus need separate patterns.

Loading & recovery

Keep the card in place. Explain what happened and offer one next step.

Module ready

Your weekly overview is ready to explore.

Explore layout

Local simulation · retry returns sample content.

Dialogs

480px maximum width · 20px padding · 24px corners. One clear decision.

Focus stays inside. Escape or Cancel closes and returns focus. Open: 280ms. Close: 160ms. Reduced motion: instant.

Form workflow

Edit a draft, then apply it. The table changes only after a successful save.

Live previewTry the fields. Apply saves this preview to the table below.

Example workspace● Notifications on

ColorReady

TypographyReady

SurfacesReady

Simulated save resultLocal example · no server or permanent storage.

Native field usage

<label>Workspace name
  <input className="field"
    aria-invalid={hasError}
    aria-describedby="name-error" />
</label>
<p id="name-error">Error message</p>

Readable data

Item	Status	Updated
Color	Ready	9 Sept 2026
Typography	Ready	9 Sept 2026
Surfaces	Draft	9 Sept 2026

Patterns

Choose a layout for the task.

Width & responsive layout

Fluid at 1440px; capped at 1600px on larger viewports. The shell includes a 240px sidebar and gutters. Reading, forms and modules stay narrower.

Reading

68ch

Form

400px

Page frame

1600px

Side module

360px

Dialog

480px

Layout preview

Main content

Viewport	Gutter	Behavior
≤ 680px	20px	One column; navigation in a drawer; modules below content or a dedicated view.
681–1199px	24px	Two columns when space permits; collapse optional context.
≥ 1200px	32px	Persistent navigation; 360px side module; main area flexes.

Cards: minimum 240px. Long tables scroll inside their own region. Check 320px, 390px, 768px and 1440px, plus 200% zoom.

Mobile

One column at 680px and below; 20px page gutters. Keep the primary task first.
Use 44px touch targets and 16px input text. Tap a dropdown again, choose an option, or tap outside to close it.
Put navigation in a drawer. Keep focused fields visible above the keyboard; account for safe areas. Never hide essential actions behind hover.

Project status

Status

Waiting for review.

Next step

Review the typography and spacing before sharing.

Supporting context follows the primary task.

Resize the browser or use split view. The same content keeps its reading order.

Tablet

681–1199px uses 24px gutters. Use two columns only when each module has enough room; stack in narrow split-screen windows.
Support touch, trackpad and keyboard equally. Keep the same controls, focus states and animations as mobile and desktop.
Reflow with available width, not device detection or orientation. Keep long tables scrollable within their own region.

Project status

Status

Waiting for review.

Next step

Review the typography and spacing before sharing.

Supporting context follows the primary task.

Resize the browser or use split view. The same content keeps its reading order.

Motion

Try each transition.

Motion rules

Use	Timing	Properties
Feedback / overlay exit	160ms	--duration-feedback
Navigation drawer	200ms	--duration-navigation
Content replacement	240ms	--duration-replace
Font preview	360ms	--duration-font
Panel entrance	280ms	opacity + translateY(10px → 0)
Theme	700ms	One page crossfade

Finish exactly at the resting state. Never animate font size, weight or container height for feedback. Reduced motion switches instantly. Rapid input must settle on the latest choice.

Theme switching

700ms fade. Follows the system until you choose a theme.

Same geometry. Different light.

Feedback & entrance

160ms feedback · 280ms entrance.

Panel preview

Fade in and settle.

Panel · fade and rise

Colors

Typography

Surfaces

List · staggered entrance

Changes saved

Your workspace is up to date.

Feedback · settle into place

Your reduced-motion preference is respected.

Engineering

Defaults for new web apps.

01

Next.js App Router

Locale routes. Server reads. Client interactions. Secrets stay on the server.

02

English & Chinese

Translate every state. Switching language keeps the current page.

03

Light & dark

OS default, saved choice and reduced motion. Use shared tokens.

04

Accounts

Supabase today. Zillion Account integration later. Verify access on the server.

05

Interaction states

Handle loading, empty, success and failure. Preserve unsaved work.

06

Validation

Check both languages/themes, keyboard access, contrast, mobile and the build.

Start a Zillion app

Run the settings example, then copy the same primitives and setup. Tokens alone do not include fonts or application behavior.

Open starter example Download primitive styles

Setup contract

// app/layout.tsx imports in order
import './tokens.css';
import './primitives.css';

// app/[lang]/layout.tsx
// Validate en/zh; load local fonts; set html lang.
// Apply stored theme before paint; wrap ThemeProvider.

// Native controls use shared classes
<input className="field" aria-invalid={hasError} />
<button className="button primary">Save</button>

// Runnable source: src/app/[lang]/starter/page.tsx
// Interaction: src/components/SettingsExample.tsx

See docs/adoption.md for the file manifest, state contract and version pinning. No authentication or persistence is implied.

Download CSS tokens

Versioned tokens. Pin the release you adopt.

Releases

Changes and adoption.

0.2.0

Current preview

2026-09-09

Soft Precision modules

Porcelain and charcoal themes, content-led modules and working examples. Card radius is now 24px; adopt matching tokens and primitive styles.

How versions work

0.x

Features and breaking changes: minor. Fixes: patch. Include migration notes for breaking changes.

1.x onward

Major: breaking. Minor: additions. Patch: fixes.

Adoption

Pin a reviewed release. Migrate each product explicitly.

Traceability

Match package, changelog and tokens. Released tags are immutable.