docs: add design spec for design system packaging
Covers Vite library mode build, Gitea npm registry publishing, snapshot + tag-based versioning, and consumer setup. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
hsiegeln
@@ -0,0 +1,192 @@
|
|||||||
|
# Design System Packaging — Design Spec
|
||||||
|
|
||||||
|
**Date:** 2026-03-18
|
||||||
|
**Status:** Approved
|
||||||
|
**Package:** `@cameleer/design-system`
|
||||||
|
**Registry:** Gitea npm registry at `gitea.siegeln.net`
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Package the Cameleer3 design system as a reusable npm library so other React applications in the Cameleer ecosystem can consume it via `npm install`. Publishing is automated via Gitea Actions.
|
||||||
|
|
||||||
|
## Decisions
|
||||||
|
|
||||||
|
| Decision | Choice | Rationale |
|
||||||
|
|----------|--------|-----------|
|
||||||
|
| Registry | Gitea built-in npm registry | Already have Gitea infrastructure |
|
||||||
|
| Package scope | `@cameleer/design-system` | Matches the org |
|
||||||
|
| Export style | Single package, flat exports | Simple DX, tree-shaking handles unused code |
|
||||||
|
| What's included | Everything (primitives, composites, layout, providers, utils, tokens) | All consuming apps are Cameleer apps |
|
||||||
|
| Build tool | Vite library mode | Already using Vite, CSS Modules first-class |
|
||||||
|
| Output format | ESM only | All consumers are Vite/ESM |
|
||||||
|
| Versioning | Tag-based releases + snapshot on every main push | Snapshots for dev, tags for milestones |
|
||||||
|
| Runner arch | ARM64 | Gitea runner is ARM64 |
|
||||||
|
| Auth secret | `REGISTRY_TOKEN` (org-level) | Existing all-access token |
|
||||||
|
|
||||||
|
## 1. Library Entry Point
|
||||||
|
|
||||||
|
New file `src/design-system/index.ts` — the single public API:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
export * from './primitives'
|
||||||
|
export * from './composites'
|
||||||
|
export * from './layout'
|
||||||
|
export * from './providers/ThemeProvider'
|
||||||
|
export * from './providers/CommandPaletteProvider'
|
||||||
|
export * from './providers/GlobalFilterProvider'
|
||||||
|
export * from './utils/hashColor'
|
||||||
|
export * from './utils/timePresets'
|
||||||
|
```
|
||||||
|
|
||||||
|
CSS (tokens.css, reset.css, all component CSS Modules) is bundled into a single `dist/style.css`. Consumers import it once:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import '@cameleer/design-system/style.css'
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. Vite Library Build Config
|
||||||
|
|
||||||
|
A separate `vite.lib.config.ts` to keep library and app builds independent:
|
||||||
|
|
||||||
|
- **Entry:** `src/design-system/index.ts`
|
||||||
|
- **Output:** `dist/index.es.js` (ESM)
|
||||||
|
- **CSS:** Extracted to `dist/style.css`
|
||||||
|
- **Externals:** `react`, `react-dom`, `react-router-dom` (peer deps, not bundled)
|
||||||
|
- **Types:** `vite-plugin-dts` generates `dist/index.d.ts` with full TypeScript declarations
|
||||||
|
- **Build script:** `"build:lib": "vite build --config vite.lib.config.ts"`
|
||||||
|
|
||||||
|
Output structure:
|
||||||
|
|
||||||
|
```
|
||||||
|
dist/
|
||||||
|
index.es.js # ESM bundle
|
||||||
|
style.css # All CSS (tokens + reset + component modules)
|
||||||
|
index.d.ts # TypeScript declarations
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Package Configuration
|
||||||
|
|
||||||
|
Updates to `package.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "@cameleer/design-system",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"type": "module",
|
||||||
|
"main": "./dist/index.es.js",
|
||||||
|
"module": "./dist/index.es.js",
|
||||||
|
"types": "./dist/index.d.ts",
|
||||||
|
"exports": {
|
||||||
|
".": {
|
||||||
|
"import": "./dist/index.es.js",
|
||||||
|
"types": "./dist/index.d.ts"
|
||||||
|
},
|
||||||
|
"./style.css": "./dist/style.css"
|
||||||
|
},
|
||||||
|
"files": ["dist"],
|
||||||
|
"sideEffects": ["*.css"],
|
||||||
|
"peerDependencies": {
|
||||||
|
"react": "^19.0.0",
|
||||||
|
"react-dom": "^19.0.0",
|
||||||
|
"react-router-dom": "^7.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `"private": true` is removed
|
||||||
|
- Existing `scripts`, `dependencies`, and `devDependencies` remain for the app build
|
||||||
|
- `peerDependencies` tells consumers what to provide
|
||||||
|
|
||||||
|
## 4. Gitea Actions CI/CD Pipeline
|
||||||
|
|
||||||
|
Workflow at `.gitea/workflows/publish.yml`:
|
||||||
|
|
||||||
|
**Triggers:**
|
||||||
|
- Push to `main` → publish snapshot (`0.0.0-snapshot.<YYYYMMDD>.<short-sha>`) with `dev` dist-tag
|
||||||
|
- Push tag `v*` → publish stable release (e.g., `1.0.0`) with `latest` dist-tag
|
||||||
|
|
||||||
|
**Steps:**
|
||||||
|
1. Checkout at ref
|
||||||
|
2. `npm ci` (install deps)
|
||||||
|
3. `npx vitest run` (gate: don't publish broken code)
|
||||||
|
4. `npm run build:lib` (build the library)
|
||||||
|
5. Determine version from tag or generate snapshot version
|
||||||
|
6. Configure `.npmrc` with `REGISTRY_TOKEN`
|
||||||
|
7. `npm publish --tag <dev|latest>`
|
||||||
|
|
||||||
|
**Runner:** ARM64 with `node:22-bookworm-slim` container image.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: Build & Publish
|
||||||
|
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches: [main]
|
||||||
|
tags: ['v*']
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
publish:
|
||||||
|
runs-on: linux-arm64
|
||||||
|
container:
|
||||||
|
image: node:22-bookworm-slim
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v4
|
||||||
|
- run: npm ci
|
||||||
|
- run: npx vitest run
|
||||||
|
- run: npm run build:lib
|
||||||
|
- run: |
|
||||||
|
if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
|
||||||
|
VERSION="${GITHUB_REF_NAME#v}"
|
||||||
|
npm version "$VERSION" --no-git-tag-version
|
||||||
|
TAG="latest"
|
||||||
|
else
|
||||||
|
SHORT_SHA=$(echo "$GITHUB_SHA" | head -c 7)
|
||||||
|
DATE=$(date +%Y%m%d)
|
||||||
|
npm version "0.0.0-snapshot.${DATE}.${SHORT_SHA}" --no-git-tag-version
|
||||||
|
TAG="dev"
|
||||||
|
fi
|
||||||
|
echo "//gitea.siegeln.net/api/packages/cameleer/npm/:_authToken=${{ secrets.REGISTRY_TOKEN }}" > .npmrc
|
||||||
|
npm publish --tag "$TAG"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. Consumer Setup
|
||||||
|
|
||||||
|
In any consuming app (e.g., `cameleer3-server/ui`):
|
||||||
|
|
||||||
|
**1. Add `.npmrc` to project root:**
|
||||||
|
|
||||||
|
```
|
||||||
|
@cameleer:registry=https://gitea.siegeln.net/api/packages/cameleer/npm/
|
||||||
|
//gitea.siegeln.net/api/packages/cameleer/npm/:_authToken=${GITEA_TOKEN}
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. Install:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# During development (snapshot builds)
|
||||||
|
npm install @cameleer/design-system@dev
|
||||||
|
|
||||||
|
# For stable releases (later)
|
||||||
|
npm install @cameleer/design-system
|
||||||
|
```
|
||||||
|
|
||||||
|
**3. Use:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Import styles once at app root
|
||||||
|
import '@cameleer/design-system/style.css'
|
||||||
|
|
||||||
|
// Import components
|
||||||
|
import { Button, Input, Modal, AppShell, ThemeProvider } from '@cameleer/design-system'
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. Documentation Updates
|
||||||
|
|
||||||
|
Update `CLAUDE.md` and `COMPONENT_GUIDE.md` in this repo with:
|
||||||
|
|
||||||
|
- The package name and registry URL
|
||||||
|
- How consuming apps should configure `.npmrc`
|
||||||
|
- Import patterns for consumers (`@cameleer/design-system` instead of relative paths)
|
||||||
|
- Note that `style.css` must be imported once at the app root
|
||||||
|
|
||||||
|
This ensures other AI agents working on consuming Cameleer apps understand how to use the design system.
|
||||||
Reference in New Issue
Block a user