@0gfoundation/design-system

@0gfoundation/design-system

Design tokens and UI components shared across 0G front-end projects.

Status: infrastructure only. The token layer works and is installable. There are no components yet — those are authored by designers through the workflow below, not pre-populated from another product.

设计师从这里开始 — in Chinese, because that is the language its readers work in:

1. DESIGNER-ONBOARDING.zh-CN.md — what is already here, the one file to rewrite first, the six rules a component has to hold to, and how to read the gate.
2. BUILDING-COMPONENTS.zh-CN.md — what to build and in what order (taken from the consuming product's real import counts, not from a list of what a design system "should" have), a worked component and its story, and what "done" means.

What is here

Install

pnpm add @0gfoundation/design-system

Then, in the app's stylesheet, before your own @theme blocks:

@import '@0gfoundation/design-system/theme.css';

Rebranding

Redefine the raw triples; never edit base.css. The indirection is the point — base.css binds --color-primary to var(--primary), so a product supplies its own --primary and every component that references bg-primary follows.

:root  { --primary: 158 64% 32%; }
.dark  { --primary: 158 50% 62%; }

Values are bare H S% L% with no hsl() wrapper, because base.css adds it. That is what lets a use site apply an alpha — hsl(var(--primary) / 0.5) — without a second token.

Adding components

Components come from designers working in this repo, one at a time, each with a story. The gates that make that safe are @0gfoundation/design-collab:

pnpm design:install-drivers   # git merge drivers — designers never resolve a token conflict by hand
pnpm design:start             # branch topology + PR skeleton, before writing code
pnpm design:check             # every gate CI runs, locally, all failures at once

Two things that will bite

Tailwind resolves @import itself. An imported file is never handed to the bundler as its own module, so a Vite transform matching tokens/*.css will never see these files. Anything rewriting the @theme blocks — a Storybook @theme static pass, for instance — must inline the imports first. Matching filenames looks correct and silently does nothing; that failure cost 28 of 145 variables in the product this was extracted from, with a green build.

Node 22.15 is a floor, not a preference. Below it module-alias cannot register the aliases the Storybook Next.js plugin needs, and the failure surfaces as Cannot find module 'sb-original/default-loader' — an error naming neither Node nor a version.

Not yet verified

No downstream project has installed this. Until one has, these are untested: the published package's install path, whether the peer range on Tailwind is right, and whether rebranding by redefining :root is ergonomic enough or wants a preset API instead. Version stays 0.0.0 until that happens.