zilliz-design-system 1.0.0

package/README.md

@@ -0,0 +1,474 @@
+# 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
+
+The public package is `zilliz-design-system`. Consumers must pin an exact version:
+
+```bash
+pnpm add -E zilliz-design-system@1.0.0
+```
+
+Do not use `latest`, `^`, `~`, Git branches, or raw commits. Supported CSS imports include:
+
+```css
+@import 'zilliz-design-system/website/zilliz/styles.css';
+@import 'zilliz-design-system/website/zilliz/styles-light.css';
+@import 'zilliz-design-system/foundations/tokens/semantic.css';
+```
+
+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-mode 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 — consumers link only this
+│   │   ├── skin/dark.css                 roles -> dark values + this line's own --z-*
+│   │   ├── skin/light.css                roles -> warm off-white light values
+│   │   ├── styles-light.css              light entry point (same chain, light skin)
+│   │   ├── 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](./foundations/templates/dependency-registry.template.md)**.
+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/`](./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 entry points are
+`styles.css` (dark) and `styles-light.css` (light).
+
+Import order is precedence, as set in `website/zilliz/styles.css`:
+`fonts -> primitives -> semantic -> skin/dark -> 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:
+
+```css
+--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`](./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`](./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`](./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

package/foundations/tokens/fonts.css

@@ -0,0 +1,5 @@
+/* Self-hosted Geist / Geist Mono (latin subsets), copied from zilliz.com public/fonts */
+@font-face{font-family:'Geist';font-style:normal;font-weight:400 700;font-display:swap;src:url('../assets/fonts/geist-sans-latin-v5.woff2') format('woff2');unicode-range:U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD}
+@font-face{font-family:'Geist';font-style:normal;font-weight:400 700;font-display:swap;src:url('../assets/fonts/geist-sans-latin-ext-v5.woff2') format('woff2');unicode-range:U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF}
+@font-face{font-family:'Geist Mono';font-style:normal;font-weight:400 700;font-display:swap;src:url('../assets/fonts/geist-mono-latin-v5.woff2') format('woff2');unicode-range:U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD}
+@font-face{font-family:'Geist Mono';font-style:normal;font-weight:400 700;font-display:swap;src:url('../assets/fonts/geist-mono-latin-ext-v5.woff2') format('woff2');unicode-range:U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF}