open-design/design-systems/kami/DESIGN.md

Design System Inspired by kami (紙 / 纸)

Category: Editorial & Print Editorial paper system: warm parchment canvas, ink-blue accent, serif-led hierarchy. Built for resumes, one-pagers, white papers, portfolios, slide decks — anything that should feel like high-quality print rather than UI. Multilingual by design (EN · zh-CN · ja).

1. Visual Theme & Atmosphere

kami compresses into one sentence: warm parchment canvas, ink-blue accent, serif carries hierarchy, no cool grays, no hard shadows. It is not a UI framework — it is a constraint system for the page, designed to keep deliverables stable, clear, and unmistakably printed. The name reads as kami / 紙 / 纸 — the same word for "paper" across Japanese and Chinese — and the system is co-designed across English, Simplified Chinese, and Japanese typesetting from the ground up, not retrofitted.

The page background is parchment (#f5f4ed), never pure white. Text sits on cream. The single chromatic move is ink-blue (#1B365D) — used on section numbers, primary CTAs, the left rule of a quote, the W500 weight in a metric. Everything else is a warm neutral with a yellow-brown undertone; cool blue-grays are absent on purpose.

Hierarchy is carried almost entirely by serif type at a single weight (500). There is no bold, no italic, no second accent color. Density is achieved through tight line-heights (1.10–1.55), four-level gray ramps, and ring/whisper shadows that act as halos rather than drops. The aesthetic borrows from editorial print, technical white papers, and old typewritten correspondence — the goal is "good content on good paper," not "modern app UI."

Key Characteristics:

• Warm parchment canvas (#f5f4ed) — never #ffffff
• Single accent: ink-blue (#1B365D), covers ≤ 5% of any surface
• All grays warm (R ≈ G > B), no cool blue-grays anywhere
• Serif everywhere for hierarchy: Charter (EN), TsangerJinKai02 / Source Han Serif (CN), YuMincho (JA)
• Locked at weight 500 — no synthetic bold (700/900) and no italic
• Tight print rhythm (line-heights 1.10–1.55), much denser than typical web body
• Depth via 1px rings and whisper shadows (0 4px 24px rgba(0,0,0,0.05)), never hard drop shadows
• Tag fills are solid hex (e.g. #E4ECF5), never rgba() — print renderers double-paint alpha tags
• Numbers sit in font-variant-numeric: tabular-nums so columns of metrics don't shimmy

2. Color Palette & Roles

Brand

• Ink Blue (#1B365D): The only chromatic color. CTAs, section numbers, link text on light surfaces, the left rule on a section title or quote, the active state of a switcher, the W500 metric value.
• Ink Light (#2D5A8A): Brighter variant, only for links sitting on dark surfaces.

Rule: ink-blue covers ≤ 5% of document surface area. More than that turns into ornament and the restraint collapses.

Surface

• Parchment (#f5f4ed): The page background — warm cream, the emotional foundation. Never replace with white.
• Ivory (#faf9f5): Cards and lifted containers. Sits one half-shade brighter than parchment.
• Warm Sand (#e8e6dc): Default button background, secondary interactive surfaces.
• Dark Surface (#30302e): Dark-theme containers — warm charcoal, not slate.
• Deep Dark (#141413): Dark-theme page background. Olive-tinted near-black, never #000000.

Text (four levels — no fifth)

• Near Black (#141413): Primary text. Slight olive warmth, gentler than pure black.
• Dark Warm (#3d3d3a): Secondary text, table headers, link defaults.
• Olive (#504e49): Subtext, captions, descriptions. (JA override: #4d4c48 because YuMincho strokes are thinner.)
• Stone (#6b6a64): Tertiary — dates, metadata, meta labels.

Border

• Border (#e8e6dc): Primary border — section dividers, card edges, table headers.
• Border Soft (#e5e3d8): Row separators, inner dividers, subtle internal lines.

Tag tints (solid, NOT rgba)

Print renderers (WeasyPrint and friends) double-paint alpha fills, leaving a visible "double rectangle" on zoom. Tag and chip backgrounds must be solid hex, pre-blended over parchment:

Effective alpha of #1B365D over parchment	Solid hex
0.08	#EEF2F7
0.14	#E4ECF5
0.18 (default tag)	#E4ECF5
0.22	#D0DCE9
0.30	#D6E1EE

Gradient System

kami is gradient-free by default. The only sanctioned gradient is the soft tag brush running #D6E1EE → #E4ECF5 → #EEF2F7 left-to-right at very low contrast — used at most once per page on a single decorative tag. Do not introduce hero gradients, brand-color washes, or backdrop-filter blurs.

Forbidden colors

• #ffffff as a page background
• #000000 anywhere
• Any cool-gray surface (#f8f9fa, #f3f4f6, slate-*)
• Any second saturated color (no second accent — pick ink-blue or pick nothing)

3. Typography Rules

Font Stacks

/* English (default) */
--serif: Charter, Georgia, Palatino, "Times New Roman", serif;

/* Chinese */
--serif: "TsangerJinKai02", "Source Han Serif SC", "Noto Serif CJK SC",
         "Songti SC", "STSong", Georgia, serif;

/* Japanese */
--serif: "YuMincho", "Yu Mincho", "Hiragino Mincho ProN",
         "Noto Serif CJK JP", "Source Han Serif JP",
         "TsangerJinKai02", Georgia, serif;

/* Mono — must include CJK fallback so labels/comments don't render as boxes */
--mono: "JetBrains Mono", "SF Mono", "Fira Code", Consolas, Monaco,
        "TsangerJinKai02", "Source Han Serif SC", monospace;

/* Sans always equals serif. There is no separate sans-serif family. */
--sans: var(--serif);

When to swap the stack

The three stacks above are alternative values for --serif, not three families layered together. When generating an artifact, set the primary stack on :root based on the dominant language of the content; let the browser's per-glyph fallback resolve mixed-script text inline. Concretely:

• <html lang="en"> (or English-dominant content) → leave --serif on the EN stack. CJK glyphs that appear inline will fall through to the system Han fallback.
• <html lang="zh-CN"> → override --serif to the CN stack on :root or on html[lang="zh-CN"]. Latin glyphs render via the Georgia tail of the stack.
• <html lang="ja"> → override --serif to the JA stack and apply the --olive: #4d4c48 text-color override (YuMincho strokes are thinner; the standard olive looks anemic against parchment).
• Multi-language artifacts (e.g. a deck with one Japanese chapter): set the dominant-language stack on :root, then scope the override on a wrapper element (section[lang="ja"] { --serif: …; }). Do not chain all three families inside a single font-family — that dilutes the visual character of every page.

Hierarchy (screen, px)

The hierarchy table below is sized for screen-rendered web pages (resume, one-pager, portfolio shown at desktop width). For other surfaces, scale from the print pt baseline using these ratios — the same rules the kami slides.py template applies:

Surface	Macro tokens (font, padding)	Micro tokens (border, radius, tracking)
Page / web artifact (one-pager, resume, white paper)	print pt × ~1.33	print pt × 1
Slide / 1920×1080 deck	print pt × ~1.6	print pt × ~0.6

Concretely: a 22pt H1 in print becomes ~29px on a web page and ~36px on a slide; an 8pt letter-spacing value that reads as confident in print drops to ~5px on a slide. Letter-spacing always uses the slide micro ratio — print tracking applied at slide scale falls apart.

Role	Family	Size	Weight	Line-height	Letter-spacing	Notes
Hero / Display	serif	96–106px	500	1.05–1.10	-1.2px	One per page max — cover or one-pager hero
Display CN/JA	serif	48–64px	500	1.10–1.12	0–0.3px	CJK glyphs need looser tracking and smaller absolute size
Section title	serif	28–32px	500	1.20	0.4px	Anchors a chapter; preceded by section number
H2	serif	22px	500	1.25	0	Subsection
H3	serif	17–18px	500	1.30	0	Item title, card heading
Manifesto / pull quote	serif	20px	400	1.65	0.05em	The one place letter-spacing earns its keep
Lede	serif	15–16px	500	1.55	0	Intro paragraph under a section title
Body	serif	14px	400	1.55	0 (EN) · 0.35px (CN) · 0.02em (JA)	Reading body
Body dense	serif	13–14px	400	1.40–1.45	0	Resume, one-pager, dense lists
Caption	serif	12px	500	1.45	0	Notes, figure captions
Eyebrow / overline	sans	12px	500	1	1.2px, uppercase	Section eyebrow, switcher, meta header
Label	sans	12px	500	1.35	0.4px, uppercase	Small inline label, ink-blue if active
Mono / spec	mono	12–13px	400	1.55	0.4px	Hex codes, type specs, code

Weight rules

• Serif uses only weights 400 and 500. No 600, no 700, no 900.
• strong { font-weight: 500 } is explicitly set so browsers don't synthesize bold.
• Sans labels may use 500 or 600 at small sizes for legibility.
• No italic anywhere. No font-style: italic. If emphasis is needed, switch the color to ink-blue or wrap in a tag.

Line-height

• Tight headline: 1.10–1.30 (display, H1, H2)
• Dense body: 1.40–1.45 (resume, one-pager, dense lists)
• Reading body: 1.50–1.55 (long-form chapters, letters)
• Label / caption: 1.30–1.40

Forbidden: 1.6+ (web rhythm, floats off the page) and 1.0–1.05 (lines collide except at giant display sizes).

Letter-spacing

• EN body: 0
• CN body (TsangerJinKai02): 0.35px to compensate for the font's natural density
• JA body: 0.02em
• All-caps overlines and small labels (< 10pt): +0.5 to +1.2px is mandatory
• Display CJK at 24px+: 0.2–1px of optical breathing room
• On slides, tracking is roughly half of print values — 8px tracking that reads as confident in a printed deck disintegrates at slide scale.

Tabular-nums contexts

font-variant-numeric: tabular-nums is mandatory anywhere kami numbers stack vertically or sit alongside other numbers — uneven proportional digits read as a layout bug at print resolution. Apply it to:

• Metric values (the big ink-blue number in .metric-value) and any side-by-side metric row
• Slide footers and slide counters (02 / 05), page numbers, deck pagination
• Section numbers in chapter heads (01, 02, …) when they appear in a stacked TOC
• Resume dates, employment ranges, and education years
• Financial figures: revenue, ARR/MRR, valuations, tables of P&L line items
• White-paper and equity-report data tables (every numeric column)
• Stat-dashboard hero numbers and KPI grids
• Changelog version numbers (1.4.2 → 1.4.3) and any inline release dates
• Any inline numeric span inside a paragraph that compares values (from 142 to 168)

Do not apply tabular-nums to running prose where a single number appears mid-sentence — proportional digits read better there. The rule is "stacks and tables, yes; sentences, no."

4. Component Stylings

Cards / Containers

background: var(--ivory);             /* never parchment — cards lift one shade */
border: 1px solid var(--border);
border-radius: 8px;                   /* default; featured cards 12px; hero 16–24px */
padding: 28px 28px 24px;              /* component interior */
transition: box-shadow 0.2s;
/* Hover lifts via whisper shadow only — no transform, no brightness shift */
&:hover { box-shadow: 0 4px 24px rgba(0,0,0,0.05); }

Buttons

.btn-primary {
  background: var(--brand);                    /* #1B365D */
  color: var(--ivory);
  box-shadow: 0 0 0 1px var(--brand);          /* ring shadow as edge */
  padding: 8px 14px;
  border-radius: 8px;
  font: 500 12px/1 var(--sans);
  letter-spacing: 0.4px;
}
.btn-secondary {
  background: var(--warm-sand);
  color: var(--dark-warm);
  box-shadow: 0 0 0 1px var(--border);
}
.btn-ghost {
  background: transparent;
  color: var(--brand);
  box-shadow: 0 0 0 1px var(--brand);
}

Tags / Chips

.tag {
  font: 500 12px/1 var(--sans);
  padding: 2px 7px;
  border-radius: 2px;
  color: var(--brand);
  background: #EEF2F7;        /* solid hex, NOT rgba */
  letter-spacing: 0.4px;
}
.tag.standard { background: #E4ECF5; padding: 2px 8px; border-radius: 4px; }

/* The single sanctioned gradient — see §2 "Gradient System".
 * Use at most once per page on a "featured" or "new" tag. The gradient
 * runs darkest-to-lightest left-to-right so the eye reads it as a
 * watercolor wash, not a button highlight. */
.tag.brush {
  background: linear-gradient(to right, #D6E1EE, #E4ECF5 70%, #EEF2F7);
}

<!-- Example: a single brush tag flagging the new chapter in a long doc -->
<span class="tag brush">New · Edition 02</span>

Quote

.quote {
  border-left: 2px solid var(--brand);
  padding: 4px 0 4px 14px;
  font: 500 15px/1.55 var(--serif);
  color: var(--olive);
}

Section title pattern

<div class="section-head">
  <p class="section-num">01</p>            <!-- ink-blue, 14px serif, tracking 0.4px -->
  <h2 class="section-title">Color</h2>     <!-- 32px serif 500 -->
  <p class="section-lede">Optional one-line description in olive.</p>
</div>

The number is set in the same serif as the title, in ink-blue, the same size as caption text. There is no underline, no left bar, no eyebrow — the number is the marker.

Metrics

<div class="metric">
  <div class="metric-value">8.4×</div>     <!-- serif 500 24px ink-blue, tabular-nums -->
  <div class="metric-label">faster ship</div> <!-- serif 12px olive -->
</div>

Numbers always sit in font-variant-numeric: tabular-nums so adjacent metrics align.

Lists

ul.dash {
  list-style: none; padding: 0;
}
ul.dash li {
  position: relative; padding-left: 14px;
}
ul.dash li::before {
  content: "\2013";          /* en-dash, ink-blue */
  position: absolute; left: 0;
  color: var(--brand);
}

Bullets are en-dashes in ink-blue, never filled discs.

Code block

.code {
  background: var(--ivory);
  border: 1px solid var(--border);
  border-radius: 6px;
  padding: 12px 14px;
  font: 12px/1.55 var(--mono);
  color: var(--near-black);
  white-space: pre;
}
.code .k { color: var(--brand); }   /* keyword */
.code .c { color: var(--stone); }   /* comment */

5. Layout Principles

Page geometry (print A4)

Document	Top	Right	Bottom	Left
Resume (dense)	11mm	13mm	11mm	13mm
One-Pager	15mm	18mm	15mm	18mm
Long Doc	20mm	22mm	22mm	22mm
Letter	25mm	25mm	25mm	25mm
Portfolio	12mm	15mm	12mm	15mm

Rule: denser = smaller margins, more formal = larger margins.

Web / screen pages

• Max content width: 1120px, centered, with padding: 88px 64px 120px on desktop.
• Section gap: 72px between top-level sections.
• Card-grid columns: 2 by default at desktop; collapse to 1 below 768px.
• Table columns sized in absolute px (not %), so kami tables don't reflow into spaghetti.

Slides (1920×1080)

• Four-side padding baseline: --slide-pad: 80px.
• Padding-top of a content slide: 72–80px (print is 96–120px; slides are more compact).
• Sizing follows the surface ratios from §3 ("Hierarchy"): macro tokens × 1.6, micro tokens × 0.6 against the print pt baseline.
• Cover and chapter slides may flip background to ink-blue (#1B365D) with ivory text; everything else stays on parchment.

6. Depth & Elevation

Three sanctioned levels — that is the entire system:

Level	Treatment	Use
Flat (0)	No shadow, no border	Body text, manifesto, paragraphs on parchment
Ring (1)	1px solid var(--border) or 0 0 0 1px var(--brand)	Cards, primary buttons, table edges
Whisper (2)	0 4px 24px rgba(0,0,0,0.05)	Hovered cards, lifted hero containers, screenshots

Forbidden:

• Hard drop shadows (0 12px 40px rgba(0,0,0,0.25) and the like) — the page is paper, not a UI panel
• Neumorphism, glassmorphism, backdrop-filter blurs
• Multi-layer composite shadows

Border radius scale

2px → 4px → 6px → 8px (default) → 12px → 16px. Tags hover at 2–4px, buttons and cards at 8px, featured / hero containers at 12–16px. Anything above 16px is reserved for cover-slide visuals.

7. Do's and Don'ts

Do

• Use parchment (#f5f4ed) as the page background — the warm cream tone is the kami personality.
• Use a single serif weight (500) for every heading; let size carry hierarchy.
• Use ink-blue (#1B365D) only for primary CTAs, section numbers, links, the left rule of a quote, and the W500 in metrics.
• Keep every gray warm (yellow-brown undertone). When in doubt, sample with R ≈ G > B.
• Use ring shadows or whisper shadows for elevation; never hard drops.
• Set tag backgrounds as solid hex pre-blended over parchment, never rgba().
• Set numbers in font-variant-numeric: tabular-nums.
• Pair the section number with the section title in the same serif — no eyebrow needed.
• Default bullets to ink-blue en-dashes (–).

Don't

• Don't use #ffffff as page background, anywhere.
• Don't introduce a second accent color or a chromatic gradient.
• Don't use cool blue-grays (slate-*, #f3f4f6, #6b7280). Every neutral is warm.
• Don't use bold (700+) on serif — weight 500 is the ceiling.
• Don't use italic anywhere. No font-style: italic. Swap to ink-blue or a tag instead.
• Don't use sans-serif for headlines or body — sans is reserved for eyebrows, switchers, and small labels (and the sans stack literally equals the serif stack).
• Don't drop body line-height below 1.4 or push it above 1.55 — that range is kami's reading rhythm.
• Don't use round-disc bullets, drop shadows, or pill-shaped chips with heavy borders.
• Don't apply backdrop-filter, mix-blend-mode, or any modern compositing trick — the system targets print fidelity.

8. Responsive Behavior

Breakpoints

Name	Width	Key Changes
Phone	< 768px	Single column. Hero 46px, section title 24px, manifesto 17px. Card padding drops to 20px 16px. Hide .hero-tokens row.
Tablet	768–979px	Most 2-col grids hold; switch tag tints from 5 to 3 columns.
Desktop	≥ 980px	Full 2-col / 4-col grids, JA gets white-space: nowrap rescue rules on long ledes.

Touch targets

• Buttons keep 8 14px padding minimum.
• Tap targets stay above 44×44 by giving cards generous internal padding rather than oversizing chrome.

Print

• @page { size: A4; margin: 14mm 16mm; background: #f5f4ed; }.
• Section, hero, family, comp, swatch, tint, quote, blockquote, pre, tr, anti-pattern blocks all use break-inside: avoid so kami pages don't snap mid-card.
• -webkit-print-color-adjust: exact is required so the parchment background actually reaches paper.

9. Agent Prompt Guide

Quick Color Reference

• Page Background: "Parchment (#f5f4ed)"
• Card Surface: "Ivory (#faf9f5)"
• Brand / CTA: "Ink Blue (#1B365D)"
• Primary Text: "Near Black (#141413)"
• Secondary Text: "Dark Warm (#3d3d3a)"
• Subtext / Caption: "Olive (#504e49)"
• Tertiary / Meta: "Stone (#6b6a64)"
• Border: "Border (#e8e6dc)"
• Tag fill (default): "#E4ECF5 solid (NOT rgba)"

Example Component Prompts

• "Build a kami one-pager hero on Parchment (#f5f4ed). Eyebrow row in 12px sans uppercase Stone (#6b6a64), letter-spacing 1.2px. Headline in serif 500 at 96px Near Black (#141413), line-height 1.05, letter-spacing -1.2px. Tagline below in serif 500 at 21px Olive (#504e49)."
• "Design a kami section header. A two-line stack: section number 01 in serif 500 at 14px Ink Blue (#1B365D) tracking 0.4px, then the title in serif 500 at 32px Near Black. Optional lede in serif 500 at 16px Olive."
• "Render a kami metric row of three metrics. Each metric is a vertical pair: value in serif 500 at 24px Ink Blue with font-variant-numeric: tabular-nums, label in 12px Olive. Gap between metrics: 28px."
• "Build a kami card on Ivory (#faf9f5) with 1px Border (#e8e6dc), 8px radius, 28px padding. Title in serif 500 at 16px Near Black. Hint underneath in 12px mono Stone. On hover, add a whisper shadow 0 4px 24px rgba(0,0,0,0.05). No transform, no color shift."
• "Build a kami slide cover at 1920×1080. Background ink-blue (#1B365D). Centered title in serif 500 at 96px Ivory (#faf9f5). Below, a 1px ivory rule, 96px wide. Author and date below in serif 500 at 18px Ivory at 70% opacity."

Iteration Guide

1. Start by checking the gray temperature. If a gray reads cool, the design is no longer kami. Replace with the warm ramp.
2. Audit the accent. If ink-blue covers more than ~5% of the visible surface, reduce — push elements back to Olive or Dark Warm.
3. Audit weight. Any weight above 500 on serif is wrong. Replace with weight 500 and let size carry the contrast.
4. Audit italic. No italic, ever. Swap to ink-blue color or a small tag.
5. Audit shadows. If a shadow is visible at a glance, it's too strong. The only shadows are 1px rings and the 0 4px 24px rgba(0,0,0,0.05) whisper.
6. Tag fills must be solid hex. If you wrote rgba(27, 54, 93, 0.18), replace with #E4ECF5.
7. Numbers tabular-nums. Any column of numbers without font-variant-numeric: tabular-nums will look wrong on a print render.
8. For slide work, halve tracking and scale macro tokens by 1.6. Print rhythm is too loose at 1920×1080 without the adjustment.

Attribution

Aesthetic inspiration drawn from tw93/kami (MIT, © Tw93 and contributors). kami is a Claude skill for typesetting professional documents and slide decks; the tokens, type rules, and "ten invariants" above adapt its print-first design language for use as an Open Design system.