A personal design system for Xuanwo (漩涡) — built for content. It dresses technical writing, talks, animation/idea explainers, docs, and a personal site in one calm, modern, bilingual (中文 / English) voice. The feeling: technical, modern, quietly confident, easy to read — full of texture in the details, never busy. Reference point: the restraint and precision of Linear.
Sources. This system was created from a written brief, not an existing codebase or Figma file. There are no external design sources to link. Content in the UI kits is illustrative and reflects Xuanwo's real focus areas (Apache OpenDAL, Databend, Rust storage); swap in real data when productionizing.
Consumers link one file: styles.css (tokens + fonts + base reset). Components are React, published on the global window.XuanwoDesignSystem_8e9a9d after the compiled _ds_bundle.js loads. Templates under templates/ are copy-and-edit starting points.
<link rel="stylesheet" href="styles.css">
<script src="_ds_bundle.js"></script>
<script>const { Button, Card, Callout } = window.XuanwoDesignSystem_8e9a9d;</script>Generated artifacts are ignored by Git. Rebuild them locally with:
npm install
npm run buildThis emits _ds_bundle.js, _ds_manifest.json, and _adherence.oxlintrc.json at the repo root. Use npm run clean to remove them. Template thumbnails are editor preview cache and are not regenerated by this script.
How copy is written across this brand.
- Voice — a knowledgeable peer, thinking out loud. Calm, precise, a little dry. Explains why, not just what. Never breathless, never salesy. “A good abstraction doesn't hide the cost — it makes the cost predictable.”
- Person. First person singular for the personal site (“Hi, I'm Xuanwo”, “I maintain…”). Second person (“you”) when teaching in docs/articles (“You call
op.read(path)…”). “We” only for genuinely collaborative project work. - Bilingual by design. 中文 and English sit side by side and carry equal weight — a 中文 subtitle under an English title, or a 中文 sentence closing an English paragraph (“把复杂留给库,把简单留给用户。”). 中文 is never an afterthought or a literal translation; it adds rhythm and a second register. Latin and CJK share the Source / Source Han type lineage so the mix never jars.
- Casing. Sentence case everywhere — headings, buttons, labels. Title Case is avoided. ALL-CAPS only for tiny eyebrow labels with wide tracking. 中文 uses no case but mirrors the same restraint.
- Punctuation. English uses standard punctuation. 中文 uses full-width Chinese punctuation (,。、“”) — note the comma after “复杂” is a full-width
,. Em dashes for asides. Sparing exclamation marks (effectively none). - Tone of UI copy. Short, literal, verb-first. “Read the writing”, “All posts”, “Follow”. Error/empty states are plain and blame-free.
- Numbers & jargon. Real, specific, never invented for decoration. Technical terms (
Operator, S3, async) are used directly and set in mono when they're code identifiers. - Emoji. Not used. The system has no emoji vocabulary — emphasis comes from type, weight, and the azure accent, never from emoji or decorative icons.
The low-level look and the rules behind it. All values are tokens in tokens/ — never hard-code.
- One accent, ten steps. A single azure ramp (
--azure-50…900, brand =--azure-500#0f83cf) — the monitor-screen blue from the Xuanwo logo. It does all the highlighting: links, primary buttons, active states, focus rings, section accents. No second brand color. - Cool near-neutrals carry everything else:
--bg(page) →--surface(cards) →--surface-2(fills/hover) →--surface-3(pressed). Text steps down--fg→--fg-muted→--fg-subtle→--fg-faint. - Full dual theme. Light is
:root; dark applies via[data-theme="dark"]and also follows the OS when no theme is pinned. In dark the accent brightens to#38a8ecfor contrast on near-black. Always use the semantic aliases (--accent,--fg,--surface) so a design works in both themes for free. - Semantic colors (success/warning/danger/info) each ship
solid,text,subtle(tinted bg), andbordervariants. - Imagery vibe. Cool, clean, restrained. If photos appear, prefer neutral-to-cool, low-saturation, no heavy filters or grain. The logo art is pixel-art on white.
- Families.
--font-sansSource Sans 3 (humanist, warm — UI & body) ·--font-display/--font-readingSource Serif 4 (literary serif — display headings & long-form articles) ·--font-monoFira Code (code, with ligatures) · 中文 via Noto Sans SC / Noto Serif SC, paired natively with the Source faces. - Serif for moments that matter (hero titles, article bodies, big quotes, slide titles); sans for the working interface. This pairing is the system's signature.
- Scale is a ~1.2 minor third, tightened at body sizes (default UI text 15px) for dense technical reading; long-form bumps to 18px with
--leading-relaxed(1.7) — generous for sustained 中文 + English reading. - Tracking tightens on large display (
-0.02em), neutral for body, wide only on uppercase eyebrows.
- 8px grid (
--space-*), 4px half-steps. Generous whitespace is the primary layout tool. - Small, crisp radii — default
--radius-md6px; pills (--radius-full) reserved for avatars, dots, switch tracks. Nothing is overly rounded. - Depth from hairlines, not shadows. Elevation reads through layered surfaces +
--border/--border-stronghairlines. Drop shadows are essentially banned — the only sanctioned shadows are faint, large-radius casts on floating overlays (dialog, dropdown, tooltip:--shadow-overlay/--shadow-popover), which deepen in dark mode. Cards, inputs, buttons get no shadow. - Cards =
--surface+ 1px--border+--radius-lg; interactive cards shift border/bg on hover, never lift. - Backgrounds are flat. No gradients (except an optional single subtle one if ever needed), no textures, no patterns, no full-bleed photo washes. The page is paper; type and space do the work.
- Quiet and short.
--duration-fast120ms (hover/color),--duration-base180ms (enter / theme cross-fade),--duration-slow280ms (overlays). Default easing--ease-out(gentle deceleration). No bounces, no springs, no abrupt or attention-grabbing motion (“没有突兀的动画”). Respectsprefers-reduced-motion. - Hover = a step up the surface ramp (
--surface-2) or a darker accent; never a glow or lift. Press/active = a further step down the ramp (darker), no scale shrink. Focus = a 2px accent outline (offset) for keyboard, plus a 3px translucent--ringon form fields. - Transitions animate
background-color/border-color/color— not box-shadow or transform.
- Reading measures:
--container-prose680px (articles), up to--container1080px /--container-wide1280px for app/marketing. - Sticky headers use a translucent
--bg+backdrop-filter: blurand a single hairline bottom border. Transparency/blur is used only there — content surfaces stay opaque.
- System: Lucide (
lucide.dev) — 24px grid, ~1.7px stroke, round caps/joins, outline (not filled). Its precise, technical, evenly-weighted line matches the brand. Substitution flag: there was no existing icon set in the brief, so Lucide is the chosen standard. In the UI kits, the icons are hand-inlined SVGs drawn in the Lucide style (ui_kits/*/icons.jsx, exposed aswindow.Icon) to stay dependency-free; in production, load Lucide from CDN (https://unpkg.com/lucide@latest) orlucide-react. - Format. SVG only, stroke-based,
currentColorso icons theme with text and accent. Never PNG icons. Never emoji as icons. Never Unicode glyphs standing in for icons. - Sizing. 16px inline with text, 18–20px in buttons/inputs, 24px standalone. Keep the 1.7 stroke; don't scale stroke up at large sizes without intent.
- The logo. The brand logo is a pixel-art lockup of Xuanwo where the “X” is a border-collie face (
assets/logo/wordmark.png), with a square X monogram (assets/logo/monogram.png) for tight spaces, favicons, and avatars. TheLogocomponent renders the wordmark (variant="wordmark", default) or the monogram (variant="mark"/LogoMark). The art sits on white — keep it on light surfaces (on dark, set it on a white rounded badge).assets/logo/logo.jpegis the full scene illustration used as the personal avatar. There is no vortex glyph.
Root
styles.css— the single entry point (only@imports). Link this.readme.md— this guide.SKILL.md— Agent-Skills wrapper._ds_bundle.js,_ds_manifest.json,_adherence.oxlintrc.json— generated by the compiler; never edit.
tokens/ — fonts.css (webfont @import) · colors.css (light + dark) · typography.css · layout.css (space, radii, borders, elevation, motion, z) · base.css (reset wiring tokens to elements).
assets/logo/ — wordmark.png (the primary Xuanwo wordmark, dog-face “X”) · monogram.png (the standalone “X” monogram) · logo.jpeg (full scene illustration — personal avatar).
components/ — 19 React primitives, grouped:
-
core/— Button, IconButton, Badge, Tag, Avatar, Kbd, Card, Callout, Logo + LogoMark -
forms/— Input, Textarea, Select, Checkbox, Switch -
navigation/— Tabs -
feedback/— Tooltip, Dialog -
content/— CodeBlockEach ships
.jsx+.d.ts(props) +.prompt.md(usage), and each group has a@dsCardshowcase HTML.
ui_kits/ — full-screen recreations built from the primitives:
personal-site/— landing page (header, hero, projects, writing, footer) with light/dark toggle.blog/— long-form article reading view (header, serif prose, code, callouts, sticky TOC, footer).
templates/ — copy-and-edit starting points (Design Components):
slide-deck/— an 8-slide talk deck at 1920×1080 (title, agenda, section divider, content, comparison, big quote, code, closing).
guidelines/ — the foundation specimen cards that populate the Design System tab (Colors, Type, Spacing, Brand).
- Fonts are loaded from the Google Fonts CDN (Source Sans 3, Source Serif 4, Noto Sans SC, Fira Code) rather than self-hosted — see the flag in
tokens/fonts.css. Provide.woff2files if you want offline / self-hosted webfonts. - The logo is Xuanwo's pixel-art Xuanwo wordmark (the “X” is a border-collie face) plus a standalone X monogram; the full scene illustration serves as the avatar. The vortex glyph has been removed.
- Possible next templates: a long-form article / blog post and a doc page — say the word and I'll add them.