Zilliz Design System

The Zilliz website (website/zilliz/) holds all the content. cloud/ has a filled-in light skin awaiting design sign-off; the other three lines are empty shells.

Install the published package

Working on website pages? See the handbook — docs/design-system-handbook.md — which covers architecture, local link: + hot reload, online/dev usage, and the modify→publish flow (self-contained; you can hand it to an AI assistant).

The public package is zilliz-design-system. Consumers must pin an exact version:

pnpm add -E [email protected]

Do not use latest, ^, ~, Git branches, or raw commits. Supported CSS imports include:

@import 'zilliz-design-system/website/zilliz/styles.css';
@import 'zilliz-design-system/foundations/tokens/semantic.css';

styles.css ships both skins: dark is the default, and setting data-theme="light" or data-theme="dark" on any element re-themes that subtree, so light and dark can coexist on one page. The Tokens Studio package is exported below zilliz-design-system/tokens-studio/. package.json contains the complete public export map.

Release process

Package releases use Semantic Versioning and are immutable. Normal pull requests never publish. To release, merge the version change to main, create an annotated vX.Y.Z tag, and publish a GitHub Release from that tag. .github/workflows/release.yml verifies the tag/version match, validates the package, installs its packed tarball in a clean fixture, and publishes to the public npm registry.

The npm trusted publisher is configured on the zilliz-design-system package and must name repository zilliztech/zilliz-design-system and workflow release.yml. If the publisher is not yet configured or publish permission is unavailable, stop the release; do not silently switch registries or add a personal publishing token.

Consumer repositories update through their own manually triggered synchronization workflow. That workflow pins a requested exact version, runs consumer tests/builds, and opens a pull request for design and engineering review. It never merges the pull request automatically.

Architecture

Vertical lines are dependency direction. Everything depends downward.

L2 is five separate boxes, one per line — they share nothing with each other, including behaviour. What sits here is each line's spec; the components that ship live in that line's own repo.

      Milvus site   Zilliz site       Doc        Zilliz Cloud     Collateral
           │             │             │               │               │
    ┌──────┴─────┐ ┌─────┴──────┐ ┌────┴──────┐ ┌──────┴───────┐ ┌─────┴───────┐
L2  │ milvus/    │ │ zilliz/    │ │ doc/      │ │ cloud/       │ │ collateral/ │
spec│ Hero       │ │ FeatureCard│ │ Code block│ │ DataTable    │ │ slide       │
    │ LogoWall   │ │ CtaCardBand│ │ API ref   │ │ Sidebar      │ │ whitepaper  │
    │            │ │            │ │           │ │ Empty state  │ │ booth       │
    │            │ │            │ │           │ │              │ │ meetup KV   │
    │            │ │            │ │           │ │              │ │ arch diagram│
    └──────┬─────┘ └─────┬──────┘ └────┬──────┘ └──────┬───────┘ └─────┬───────┘
           │             │             │               │               │
    ┌──────┴─────────────┴─────────────┴───────────────┴───────────────┴───────┐
    │ L1   foundations                    MUST be unified, one source          │
    │      color semantics . type scale . spacing . radius . motion            │
    │      logo / icon sources . voice . print colour (CMYK / Pantone)         │
    │      interaction + a11y rules (written standard, not shared code)        │
    │      -> CSS vars | JSON (DTCG) | .ase swatch | CC Library                │
    └──────────────────────────────────────────────────────────────────────────┘

L1 is the only layer that must be unified — 80% of consistency comes from it, and no product line needs a different brand blue.

Five product lines, six directories. The table below lists the five lines; the repo holds six directories — one shared layer (foundations) plus one per line. "Directory" below always means one of those six.

The five consumers

The L2 column is each line's directory in this repo, which holds its spec — not the repo its code ships from.

| Consumer | L1 | L2 spec | Its constraint | | --- | --- | --- | --- | | Milvus site | ✓ required | website/milvus/ | Open-source community register, deliberately distinct from the commercial site | | Zilliz site | ✓ required | website/zilliz/ | 60px hero, 100px sections, optimised for conversion | | Doc | ✓ required | website/doc/ | No system of its own; one small set of patterns | | Zilliz Cloud | ✓ required | cloud/ | 32px table rows, density, state machines, keyboard reachability | | Collateral | ✓ + print tokens | collateral/ | Slides / whitepapers / booth / meetup art / architecture diagrams; needs its own print colour standard |

L2 is deliberately not shared. The site optimises for conversion and the SaaS optimises for information density — opposite constraints. Forcing them onto one Button grows twelve variants until nobody dares touch it. Adobe, Brad Frost and EightShapes all draw the line in the same place: unifying tokens is a net gain, unifying components is a liability.

The three web properties are grouped under website/ but their L2 is not merged. They share L1; their component appearance and behaviour stay independent. The grouping exists only because they are all web and share a toolchain.

What this repo is the source of truth for — and what it is not

It owns design values. It does not own how a line's features hang together. That second kind of knowledge is derived from each line's own code and stays in that line's own repo.

    ┌──────────────────────────────────────────────────────────────────────────┐
    │ zilliztech/zilliz-design-system     SOURCE OF TRUTH for design values    │
    │                                                                          │
    │ foundations/tokens/       -> CSS vars | JSON (DTCG) | .ase swatch        │
    │ DESIGN.md                 -> WHAT IT LOOKS LIKE                          │
    │ foundations/templates/    -> how a line writes its own registry          │
    └──────────┬────────────────────────┬───────────────────────┬──────────────┘
               │ import                 │ read                  │ publish / mirror
               ▼                        ▼                       ▼
   ┌──────────────────────────┐ ┌────────────────────┐ ┌─────────────────────────┐
   │ EACH LINE'S OWN REPO     │ │ AI agent           │ │ Figma / CC Library      │
   │ zilliz.com . cloud       │ │ reads it before    │ │ where designers         │
   │ milvus . docs            │ │ writing any UI     │ │ pick values             │
   │                          │ │                    │ │ MIRROR, not source      │
   │ its components import    │ └────────────────────┘ └─────────────────────────┘
   │ the tokens               │
   │                          │
   │ dependency-registry.md   │  SOURCE OF TRUTH for that line's own flows.
   │  -> WHAT BREAKS IF YOU   │  An agent derives it from THAT repo's code and
   │     CHANGE X             │  it is maintained there. It never lives in the
   └──────────┬───────────────┘  design system repo.
              │
      ┌───────┴────────┐
      ▼                ▼
  no drift        "changing onboarding
  across the       hits these 5 screens"
  five lines

Figma and CC Library are mirrors of this repo, not the other way round. The values a designer picks in Figma come from foundations/tokens/; a token changes in the repo only. See SYNC.md.

The two markdown files are projections for agents at different levels of abstraction, and they live in different repos because they answer to different owners. DESIGN.md gives an agent the persistent memory of the design system it otherwise lacks, and is maintained here. The dependency registry answers what breaks if you change X, at flow and screen level and deliberately not descending to UI components — it is built from a line's own code by the people who work in that code. This repo ships only the template. Both are plain markdown with no build pipeline.

Directory structure

zilliz-design-system/
│
├── README.md                     this file
├── DESIGN.md                     the agent-readable form of L1
├── SKILL.md                      Agent Skills entry point
├── sources.md                    source repos + screen map
├── SYNC.md                       how values travel in and out of this repo
│
├── foundations/                  L1 · must be unified
│   ├── tokens/
│   │   ├── primitives.css            colour / type / spacing / radius / shadow / motion scales
│   │   ├── semantic.css              role names. The only layer components may reference
│   │   ├── fonts.css                 Geist @font-face
│   │   └── print.css                 CMYK / Pantone (empty — values must be set by a human)
│   ├── tokens-studio/                W3C DTCG Dark/Light color + typography import package
│   ├── assets/
│   │   ├── fonts/                    Geist / Geist Mono woff2
│   │   └── logos/                    312 logos from all four repos, sorted by what
│   │       ├── README.md                 a logo is — index, provenance, tinting contract
│   │       ├── build-browser.py          generates the searchable browser page
│   │       ├── manifest.json             machine-readable index
│   │       ├── zilliz/  products/        ours — never recoloured
│   │       ├── customers/ global cn jp color
│   │       ├── partners/ cloud tech
│   │       └── competitors/ integrations/ sdk/ social/ media/ compliance/ badges/
│   ├── voice.md                      voice and copy rules (shared across lines)
│   ├── interaction.md                interaction + a11y rules every line must meet
│   ├── icon.md                       1–1.5px stroke / currentColor / 8–20px
│   ├── templates/                    how to write DESIGN.md and the dependency registry
│   ├── guidelines/                   23 Colors / Type / Spacing / Brand specimen cards
│   └── dist/                         tokens.css | tokens.json | brand.ase (to be built)
│
├── website/                      L2 spec · the three web properties
│   ├── zilliz/                       Zilliz website             [spec complete]
│   │   ├── DESIGN.md
│   │   ├── styles.css                    entry point — the only file consumers link; ships both skins
│   │   ├── skin/dark.css                 :root default + [data-theme="dark"] — dark values + this line's own --z-*
│   │   ├── skin/light.css                [data-theme="light"] — warm off-white light values
│   │   ├── layout.css                    container / rhythm / control sizing / one-off type
│   │   ├── layout.md                     the rules and reasoning behind those values
│   │   ├── tokens.archived.md            [archived] pre-migration tokens -> where each went
│   │   ├── imagery.md                    isometric renders at 70% opacity
│   │   ├── dataviz.md                    the three benchmark greyscale tiers
│   │   ├── components/                   core cards controls data layout (24)
│   │   ├── ui_kits/website/              click-through home + customers prototype
│   │   └── assets/                       customers testimonials features cta compliance illustrations
│   ├── milvus/                       Milvus website             [empty shell]
│   │   ├── DESIGN.md
│   │   └── skin/                         to be filled in
│   └── doc/                          Doc                        [empty shell]
│
├── cloud/                        L2 spec · Zilliz Cloud (SaaS)  [empty shell]
│   ├── DESIGN.md
│   └── skin/light.css                values filled in, pending design sign-off
└── collateral/                   L2 spec · marketing collateral [empty shell]
                                      slides / whitepapers / booth / meetup art
                                      architecture diagrams

Which layers live here, and which live in the business repos

Not one line in this repo is deployed to production. It produces values and rules — the business repos consume them.

| What | Maintained where | Form | Who changes it | | --- | --- | --- | --- | | L1 foundations | This repo | CSS custom properties today; tokens.json + .ase swatches once dist/ is built | Design, review required | | L1 interaction rules | This repo | interaction.md — acceptance criteria each line implements itself, no shared code | Design + Eng, review required | | L2 spec | This repo | One DESIGN.md + skin/*.css per line, plus layout / imagery / dataviz rules and a reference implementation (components/, ui_kits/) for design and agents to read | Line design autonomy | | L2 implementation | The business repos | The component code, pages, routes and business logic that actually ship | Line engineering autonomy | | L2 dependency registry | The business repos | dependency-registry.md, derived by an agent from that repo's code. This repo ships only the template | Line PM + engineering | | Collateral | This repo | Print colour standard + Do's & Don'ts + the source of truth templates draw from (finished pieces do not enter the repo) | Design |

⚠️ The 24 components in website/zilliz/components/ are a reference implementation, not production code. Production code lives in zilliztech/zilliz.com. The versions here exist so design can see what the spec looks like, so agents have something to write UI against, and so token changes have something to run visual regression on.

Not one line of component code moves out of the business repos — the only change is swapping hard-coded colours and sizes for L1 values. That is what Phase 1's "swap tokens, touch no components" means.

How this repo connects to a line's component library

L2 is split across both sides. A line's spec — its DESIGN.md, its skin/*.css, its layout / imagery / dataviz rules — is maintained here. The components that actually ship are maintained in that line's own repo and stay there. Values are the only thing that crosses.

⚠️ Today that crossing is manual. There is no package.json in this repo, nothing is published, and foundations/dist/ is empty — its build script is still on the Phase 0 checklist. Right now "consuming L1" means a person reads a value out of foundations/tokens/ and writes it into their own code, or a page links website/zilliz/styles.css straight from a checkout.

The intended mechanism, once dist/ exists:

| Layer | What a business repo takes | What it does with it | | --- | --- | --- | | L1 | tokens.css / tokens.json | Its components reference --ds-* role names instead of hex values. This is all of Phase 1. | | L1 rules | voice.md / icon.md / interaction.md | Written standards its own code is held to; nothing is imported | | L2 | Nothing | A line's DESIGN.md and skin/ are read by its designers and agents; no code imports them |

Nothing enforces any of this yet — no lint rule, no CI check, no version contract tying a business repo to a token version. That gap is the deliberate cost of L2 autonomy at the component level, but the L1 half of it is worth closing; it is on the list below.

Which layer each Agent Skill file belongs to

| File | Layer | Notes | | --- | --- | --- | | The root DESIGN.md | L1 | Ramps, type scale, spacing, radii, role list; declares omitted for components | | A line's DESIGN.md | L2 | That line's role values + the components section + its own Do's & Don'ts | | dependency-registry.md | L2, in each line's own repo | Per line, never merged, derived from that line's code. See below |

Behaviour has no place in DESIGN.md — the official spec's components section carries only visual properties (backgroundColor / textColor / typography / rounded / padding / size / height / width) and cannot express behaviour. That is expected, not a defect.

The dependency registry is L2, on the business-repo side

It is per line and never merged — which is exactly what L2 means. It is not implementation; it is a third thing living on the same side of the boundary, in the line's own repo, for three reasons:

1. It is derived from that repo's code. An agent builds it by scanning the line's own codebase, and rescanning after a change is what keeps it current. It cannot be derived from anywhere else, so it cannot usefully live anywhere else
2. It records feature entanglement, not design knowledge — a different thing from tokens and component appearance
3. Its scope is a single product line — scope: cluster-create is Cloud's; Doc has its own. They are independent, and there is no reason to merge them

PRD is the query, not the data entry. A requirement arrives, an impact pass runs against the registry, and the result goes to design, PM and QA. Nobody fills in a column at review time.

This repo provides only the template. Each line copies it, puts it in its own repo, and maintains it there.

⚠️ cloud/dependency-registry.seed.md is staged: 13 entries derived from the real cloud-client code are captured there, to be moved into the Cloud business repo once there is a place for them. It does not stay here.

Templates: foundations/templates/.

Tokens · target shape

Two layers, one rule: a component may only reference --ds-* — never a raw ramp value, never a hard-coded hex. The 24 existing components are mid-migration and still reference --z-*; skin/dark.css bridges the two sets of names until Phase 1 ends. The rule binds every new component.

foundations/tokens/primitives.css     colour / type / spacing / radius / shadow / motion — values only, no usage
foundations/tokens/semantic.css       role names — usage only, no values
    ↓ each line assigns
website/zilliz/skin/dark.css          Zilliz website, dark
website/zilliz/skin/light.css         Zilliz website, light (warm off-white ground)
cloud/skin/light.css                  Zilliz Cloud, light

The dark and light skins implement the same role names with different values — a component never needs to know which skin it is running under. The single entry point styles.css ships both skins: dark is the bare :root default, and light activates under [data-theme="light"]. Set data-theme on any ancestor to theme that subtree, so light and dark can coexist and switch in place on one page.

Import order is precedence, as set in website/zilliz/styles.css: fonts -> primitives -> semantic -> skin/dark -> skin/light -> layout.

The role list

| Group | Roles | | --- | --- | | Surfaces | surface-page surface-raised surface-overlay surface-sunken surface-hover surface-active surface-tab-group | | Text | text-primary text-secondary text-tertiary text-muted text-faint text-inverse text-code | | Borders | border-subtle border-default border-strong border-hover border-focus | | Accent | accent accent-hover accent-subtle accent-on accent-glow | | Status | danger warning success info — shared across lines, identical values |

border-focus is new. Exactly one focus ring exists today — FeatureCard's, added during the upstream alignment (layout.css .z-feature-card:focus-visible). Every other component still has none.

Why the semantic layer is necessary

The old tokens/colors.css already had 7 semantic aliases at the bottom, but all of them were hard-bound to dark:

--z-bg-page: var(--z-black);   /* #0e0e0e */
--z-accent:  var(--z-cyan);    /* #97fdff */

The same file also held the legacy blues the SaaS product uses (--z-digital-blue: #175fff, --z-btn-blue: #3f46ff) alongside the light neutrals (--z-gray-1..4) — the site does not use them; they were simply carried over wholesale from variables.css. That is what "two systems sharing one variable table and each taking half of it" looks like in practice.

The role layer exists so that dark and light each implement the same set of names, and component code never has to know which line it is running on.

Three splits, already done

| Was | Split into | | --- | --- | | tokens/colors.css | Ramps -> foundations/tokens/primitives.css (24 --z-neutral-* steps + 3 --z-cyan-*); the decisions — #0e0e0e, cyan, #1a1a1a — -> website/zilliz/skin/dark.css | | tokens/typography.css | new-h1…h6 / new-body1…6 / weights / tracking -> primitives.css; the one-off sizes such as --z-hero-title-* -> website/zilliz/layout.css (rules in layout.md) | | tokens/spacing.css | --z-gap-* --z-radius-* -> primitives.css; --z-container-max --z-section-y --z-header-h --z-*-pad -> website/zilliz/layout.css |

From tokens/effects.css, the shadows and durations (--z-shadow-* / --z-dur-*) went into primitives.css; all 9 gradients stayed in website/zilliz/skin/dark.css — they are specific marketing visual decisions.

Two deviations from the original plan

1. website/zilliz/layout.css is a new file. The original plan folded the layout constants into layout.md, but 24 components reference variables like --z-container-max, and CSS cannot reference markdown. So the values live in layout.css and the rules and reasoning live in layout.md. Both exist.

2. website/zilliz/skin/dark.css keeps the full set of old --z-* names, because components are frozen until the end of Phase 1 and still reference them: 20 of the 22 component files use --z-*, and 15 of those already use --ds-* alongside it. The skin bridges both sets until the migration finishes. Wherever L1 already has the step, the skin only aliases it (--z-surface-2: var(--z-neutral-905)); literal values appear only where the value is genuinely this line's own decision. 145 of the 161 pre-migration --z-* names still resolve (verified); the other 16 are the retired legacy light palette. Three of the 145 changed value during the upstream alignment. Full mapping: website/zilliz/tokens.archived.md. New components use --ds-* only.

Why there is no shared behaviour layer

An earlier draft had a third layer between foundations and the product lines: one headless library of Dialog / Select / Tabs behaviour that every line would import. It was evaluated and dropped.

Behaviour is not unifiable enough to be worth it. Doc's tooltip and Cloud's tooltip differ in hover delay, in what dismisses them and in whether they can hold interactive content — real differences, not styling. Forcing them onto one implementation grows the twelve-variant component this system exists to avoid, which is the same argument that keeps appearance out of the shared layer. Three further facts pointed the same way: the highest value candidates (Dialog, Select, Tooltip) exist on no line today, so it would have been new code rather than an extraction; nothing in the split was clean, with Collapse's aria-expanded generic while its 500ms transition is the site's; and skipping it costs nothing at the foundations level. Adobe's Consonant makes the same call.

Each line writes its own components, behaviour included.

⚠️ But part of behaviour is not a matter of taste. Focus order, keyboard reachability and ARIA semantics are identical wherever they appear, are hard to get right, and getting them wrong is a defect rather than a difference of style. Dropping the shared layer must not drop those. They are now an L1 written standard: foundations/interaction.md — acceptance criteria each line implements itself and is measured against. No shared code, one shared bar.

Status by line

| Line | What it is | L1 | L2 spec | Notes | | --- | --- | --- | --- | --- | | website/zilliz | Zilliz website | ✅ split out | complete | 24 components + 2 screen prototypes + all assets | | website/milvus | Milvus website | to be wired up | empty shell | Open-source register is deliberately distinct from the commercial site; not folded into website/zilliz/ | | website/doc | Doc | to be wired up | empty shell | Will consume L1 plus a small pattern set of its own | | cloud | Zilliz Cloud (SaaS) | to be wired up | DESIGN.md + light skin only | skin/light.css has real values pending design sign-off; 13 registry entries staged. Phase 1 swaps tokens only; components untouched | | collateral | Marketing collateral | values TBD | empty shell | Slides / whitepapers / booth / meetup art / architecture diagrams; #97fdff is outside the CMYK gamut and needs a human-set value plus a press proof |

To do

Phase 0

• [x] foundations/voice.md — zero engineering work, usable by every line today
• [x] foundations/tokens/semantic.css — the role list (values filled in per line)
• [x] website/zilliz/skin/dark.css — mapping complete, every value taken from the pre-migration colors.css
• [x] foundations/tokens-studio/ — importable Dark-mode color and typography foundations for Figma
• [x] tokens/{colors,typography,spacing,effects}.css split three ways per the table above
• [x] The root DESIGN.md (L1 only, omitted for components) + website/zilliz/DESIGN.md
• [x] 13 dependency-registry entries captured from real code (staged in cloud/dependency-registry.seed.md)
• [ ] Move those entries into the Zilliz Cloud business repo — needs a location from Eng
• [x] The light ramps (--z-warm-* / --z-ink-* / --z-blue-* / --z-teal-*) + website/zilliz/skin/light.css + cloud/skin/light.css
• [ ] cloud/skin/light.css pending design sign-off — the values were derived from the site's light skin, not extracted from the existing SaaS UI
• [ ] Fill in website/milvus/skin/ — the shell exists; the relationship between the Milvus and Zilliz brand colours is undecided
• [ ] Set the values in foundations/tokens/print.css — needs a press proof; not solvable in code
• [ ] The foundations/dist/ build script (tokens.css / tokens.json / brand.ase)
• [ ] Decide how a business repo actually consumes L1 — package name, versioning and whether anything enforces it. Nothing is published today and nothing checks adherence

Needs cleanup (flagged only; content untouched for now)

• [ ] foundations/icon.md — the footer social icons are Simple Icons CDN substitutes, not the brand's own paths
• [ ] sources.md — /zilliz-agent does not exist anywhere in the 3,905-file repo snapshot; the screen map marks it (not built)
• [ ] Near-duplicate steps in the primitives.css ramps (neutral-600/595, 815/810, 865/864) — consolidate in Phase 1
• [x] The legacy blue values are promoted to L1 as --z-blue-* (the light skins' accent); only the old-name aliases remain in the dark skin
• [x] The legacy light set (--z-gray-* cold greys + the old blue names) is retired wholesale, preserved verbatim in website/zilliz/tokens.archived.md. There is now exactly one light palette

Out of scope

• Do not push changes back to upstream zilliz.com
• Do not merge L2
• Do not touch components before Phase 1 ends

Sources

Full version in sources.md. Summary:

• Distilled from: keirazhang-droid/zilliz.com @ main, reading packages/zilliz.com and packages/components/styles
• Upstream public repo: zilliztech/zilliz.com — no changes are pushed back
• Last sync: 2026-08-19T12:06Z
• /zilliz-agent was not built — no matching route, page part or i18n namespace exists in the 3,905-file repo snapshot