zilliz-design-system 1.0.0

package/DESIGN.md

@@ -0,0 +1,210 @@
+---
+version: 0.1
+name: Zilliz Foundations
+description: The visual foundation shared by every product line. Any agent writing Zilliz UI reads this first for exact values. For the Zilliz site, also read website/zilliz/DESIGN.md.
+omitted:
+  - section: components
+    reason: Component appearance diverges per product line — see each line's own DESIGN.md (website/zilliz/DESIGN.md and so on)
+colors:
+  neutral-950: "#0e0e0e"
+  neutral-935: "#111111"
+  neutral-905: "#171717"
+  neutral-890: "#1a1a1a"
+  neutral-875: "#1d1d1d"
+  neutral-865: "#202123"
+  neutral-855: "#222222"
+  neutral-845: "#242422"
+  neutral-835: "#262626"
+  neutral-815: "#2a2a2a"
+  neutral-810: "#2b2b2b"
+  neutral-795: "#2e2e2e"
+  neutral-775: "#333333"
+  neutral-760: "#363637"
+  neutral-690: "#484848"
+  neutral-620: "#595959"
+  neutral-600: "#5d5d5d"
+  neutral-595: "#5e5e5e"
+  neutral-580: "#61626d"
+  neutral-540: "#6c6c6c"
+  neutral-410: "#8a8f98"
+  neutral-240: "#b9bbc1"
+  neutral-050: "#f1f1f1"
+  neutral-020: "#fafafa"
+  neutral-000: "#ffffff"
+  cyan-100: "#d6ffff"
+  cyan-300: "#97fdff"
+  cyan-500: "#5bdfe1"
+  warm-50: "#fdfcfa"
+  warm-100: "#faf9f6"
+  warm-200: "#f5f3ee"
+  warm-300: "#e8e4dc"
+  warm-400: "#ddd8ce"
+  warm-900: "#c0bbb5"
+  ink-400: "#a8a29e"
+  ink-500: "#78716c"
+  ink-600: "#57534e"
+  ink-700: "#44403c"
+  ink-900: "#1c1917"
+  blue-100: "#e1eeff"
+  blue-650: "#3f46ff"
+  blue-800: "#181eca"
+  teal-300: "#5eead4"
+  teal-700: "#0f7668"
+  danger: "#ec4e4e"
+  warning: "#ffc300"
+  success: "#4caf50"
+  info: "#00b3ff"
+typography:
+  heading:
+    fontFamily: "Geist, -apple-system, BlinkMacSystemFont, Segoe UI, Arial, sans-serif"
+    fontWeight: 500
+    fontSize: "36px"
+    lineHeight: "44px"
+  body:
+    fontFamily: "Geist, -apple-system, BlinkMacSystemFont, Segoe UI, Arial, sans-serif"
+    fontWeight: 400
+    fontSize: "16px"
+    lineHeight: "22px"
+  mono:
+    fontFamily: "Geist Mono, ui-monospace, SFMono-Regular, monospace"
+    fontSize: "14px"
+    lineHeight: "20px"
+spacing:
+  1: "4px"
+  2: "8px"
+  3: "12px"
+  4: "16px"
+  5: "20px"
+  6: "24px"
+  8: "32px"
+  10: "40px"
+  12: "50px"
+rounded:
+  xs: "2px"
+  sm: "6px"
+  md: "8px"
+  lg: "12px"
+  xl: "24px"
+  pill: "36px"
+---
+
+## Overview
+
+This file is the **L1 foundation**: the scales and role names shared by every Zilliz
+product line. It **does not define what any component looks like**, and it **does not
+define where any colour is used** — that is each line's own business.
+
+How the two layers divide:
+
+| Layer | Directory | Covered here |
+| --- | --- | --- |
+| L1 scales + roles | `foundations/` | ✅ entirely |
+| L2 per-line appearance | `website/{zilliz,milvus,doc}/` `cloud/` `collateral/` | ❌ see each line's own DESIGN.md |
+| Interaction + a11y rules | `foundations/interaction.md` | ❌ the DESIGN.md format has no place for behaviour |
+
+**One rule: components may only reference `--ds-*` role names. Never a raw ramp value,
+never a hard-coded hex.**
+
+## Colors
+
+The `colors` in the front matter above are **ramps**, not a palette — they carry values,
+not usage. **Do not use them directly in a component.** Components use role names, which
+each line's skin assigns:
+
+| Group | Roles |
+| --- | --- |
+| Surfaces | `--ds-surface-page` `-raised` `-overlay` `-sunken` `-hover` `-active` `-tab-group` |
+| Text | `--ds-text-primary` `-secondary` `-muted` `-faint` `-inverse` `-code` |
+| Borders | `--ds-border-subtle` `-default` `-strong` `-hover` `-focus` |
+| Accent | `--ds-accent` `-hover` `-subtle` `-on` `-glow` |
+| Status | `--ds-danger` `--ds-warning` `--ds-success` `--ds-info` |
+
+**Status colours are shared across lines with identical values** — they are the only four
+entries in `colors` that may be used as final values. Every other role gets its value in
+`website/zilliz/skin/dark.css`, `website/zilliz/skin/light.css`, `cloud/skin/light.css`
+and so on.
+
+`--ds-border-focus` is a **new role**. Only `FeatureCard` has a focus ring today; every new
+component must implement one — see `foundations/interaction.md`.
+
+⚠️ The ramps contain near-duplicates (`neutral-600` / `-595`, `neutral-815` / `-810`).
+They are an inventory of what the site actually uses, not an ideal scale. **Do not add new
+greys** — pick the nearest existing step.
+
+### Never mix cold and warm greys
+
+L1 carries **two neutral families**, one per skin. **They must never be crossed:**
+
+| Ramp | Hue | Used by |
+| --- | --- | --- |
+| `--z-neutral-*` | Cold grey, near-black to white | Dark skins (the site today) |
+| `--z-warm-*` + `--z-ink-*` | Warm grey, yellow-leaning white to warm ink | Light skins |
+
+The same applies to accents: dark skins use `--z-cyan-*`, **light skins use `--z-blue-*`**
+(`#97fdff` has too little contrast on warm white to serve as a CTA). Where you need the
+same brand voice but legible on light — code, terminal, CLI — use `--z-teal-*`.
+
+## Typography
+
+Geist for everything, Geist Mono for commands, terminal chrome and inline shell.
+**There is no third typeface.**
+
+Two scales coexist:
+- **`new-h1…h6`** (60/70 -> 24/30) and **`new-body1…6`** (20/26 -> 12/16) — this is the
+  preferred set
+- Each line's own one-off sizes — **these are not L1**; they live in that line's layout file
+
+Weights: 500 by default, 400 for prose, 600 for card titles, and 700 only on the Zilliz
+site hero. Tracking is near zero; `--z-tracking-tag` (0.1em) is the **only** tracking
+allowed with all caps, and only on eyebrows and tags.
+
+## Layout
+
+Spacing comes only from the `spacing` steps. `4` (16px) is the default gap between
+elements.
+**Container width, section rhythm and header height are not L1** — they vary by medium and
+live in each line's layout file.
+
+## Elevation & Depth
+
+**Depth comes from borders and value steps, not blur.** The shadow steps L1 offers, for
+lines to use as needed:
+
+| Token | Value | Where |
+| --- | --- | --- |
+| `--z-shadow-input` | `0 1px 2px rgba(33,37,44,.08)` | Inputs |
+| `--z-shadow-terminal` | `0 24px 24px rgba(0,0,0,.15)` | Large raised surfaces |
+| `--z-shadow-menu` | `12px 24px 24px rgba(0,0,0,.25)` | Flyout menus |
+| `--z-shadow-dropdown` | `0 8px 20px rgba(0,0,0,.4)` | Dropdowns |
+
+Motion durations are L1 too: `--z-dur-fast` .15s / `--z-dur` .2s / `--z-dur-slow` .3s,
+easing `linear`. **No bounce, no spring.**
+
+## Shapes
+
+`rounded.lg` (12px) is the default card radius, `rounded.md` (8px) the default control
+radius. `pill` (36px) is for buttons only. Borders are **1px everywhere**.
+
+## Components
+
+`omitted` — see the front matter. Component appearance diverges per product line; for the
+Zilliz site read `website/zilliz/DESIGN.md`.
+
+## Do's and Don'ts
+
+**Do**
+
+- Always reference colours through `--ds-*` role names
+- When you need a new gap, pick the nearest existing `spacing` step
+- To de-emphasise text use `--ds-text-muted`; never dial down opacity yourself
+- Every newly written interactive component must implement the `--ds-border-focus` ring
+- Copy rules are in `foundations/voice.md`, icon rules in `foundations/icon.md` — both are
+  L1 and **equally binding**
+
+**Don't**
+
+- ❌ Never hard-code a hex value in a component
+- ❌ Never reference the `--z-neutral-*` / `--z-cyan-*` ramps directly
+- ❌ Never add a new type size, a new grey, or a new accent hue
+- ❌ Never add a components section to this file — that belongs to L2
+- ❌ A line's DESIGN.md **may not redefine** a token name that already exists here

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zilliz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.