@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# Design System
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The design rules and rationale live in [`DESIGN.md`](../../DESIGN.md) (repo root) and this layer's [`AGENTS.md`](AGENTS.md); dated judgment calls in [`docs/design-decisions.md`](../../docs/design-decisions.md). This layer is the implementation those documents describe. When they disagree, the code here wins and the doc gets fixed.
+
+Design system layer: design language extended by every app. It owns UI primitives, tokens, fonts, motion, chart helpers, formatters, design vocabularies (`Status`, severity, health, data-viz palette), and cross-cutting UI affordances (eject, feedback widget contracts).
+
+## Scope
+
+**Owns:**
+- UI primitives under `app/components/{container,data,element}/`
+- Design tokens, fonts, motion, chart helpers
+- Formatters and design vocabularies (`Status`, severity, health, data-viz palette)
+- Cross-cutting UI affordances (eject, feedback widget contracts)
+- CSS tokens and global stylesheet (`css/`)
+
+**Depends on:** `nuxtseo-shared` (brand marks) and the published Nuxt modules in `package.json`. No workspace package.
+
+**Consumed by:** `apps/site`, `apps/pro`, `apps/admin`, `apps/brand-kit`, and outside sites through the [npm](https://npmjs.com) package `@nuxtseo/design-system`.
+
+## Rules
+
+- Per ADR-0042 (pragmatic rule): MAY know domain *shapes*; MUST NOT import runtime services. No `useFetch`, [Drizzle](https://orm.drizzle.team), Caller, billing, auth, or `useRuntimeConfig` at module scope. [Storybook](https://storybook.js.org) test: renders with prop fixtures alone.
+- Component placement per ADR-0029. Components MUST NOT be prefixed `Pro/Admin/Tool/Docs/Learn`; the layer name is the scope.
+- One of only two layers (with `core`) every app extends.
+
+## Consuming this layer
+
+Outside this repository, install the published package and extend it.
+
+```bash
+pnpm add @nuxtseo/design-system
+pnpm add -D typescript@^6
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@nuxtseo/design-system'],
+})
+```
+
+- Peers: `nuxt` 4.6+, `vue` 3.5+, and `typescript` 5.8 to 6. The Vue SFC compiler resolves the layer's prop types through the TypeScript JS API, and TypeScript 7 has none.
+- If [pnpm](https://pnpm.io) reports ignored build scripts, allow `esbuild` and `@parcel/watcher` under `allowBuilds` in `pnpm-workspace.yaml`.
+- Import components from `#components`. The layer turns auto-imports off.
+
+### Overrides
+
+| What | How |
+| --- | --- |
+| Nuxt UI colours, slots, icons, toaster, favicon paths | `app.config.ts` in your app. It merges over the layer's `app/app.config.ts`. |
+| Tokens: colours, fonts, density, elevation | CSS custom properties in your own stylesheet, loaded after the layer's `css/global.css`. Override `--ui-*`, `--density-*`, and `--elevation-*`; never `--_depth-*`. |
+| One instance | Props and slots on the component. |
+| Icon set, chart colours, icon colour roles | The brand seams below. |
+
+Same-name shadowing does not work. A component in your `app/components/` with a layer component's name loses: the layer registers its components at priority 10. A composable with a layer composable's name is never used: layer files import each other by path. If you need a change that props, slots, tokens, or `app.config` cannot express, open an issue for a new prop or slot.
+
+### Releasing
+
+The UI packages release on their own `ui-v*` tag, apart from the `public-v*` CLI cohort.
+
+1. Set the version: `pnpm --dir layers/design-system pkg set version=X.Y.Z`. Merge it to `main` through a pull request.
+2. Check it: `pnpm release:ui:check ui-vX.Y.Z`.
+3. Pack and smoke it: `pnpm --dir layers/design-system pack --pack-destination /tmp/ui`, then `pnpm release:ui:smoke /tmp/ui/nuxtseo-design-system-X.Y.Z.tgz`.
+4. Tag the merged commit `ui-vX.Y.Z` and push the tag. `.github/workflows/publish-ui-packages.yml` verifies, packs, smokes, and publishes. A prerelease such as `X.Y.Z-beta.1` goes to the `next` dist-tag.
+
+## Brand seams
+
+A site that extends this layer cannot shadow its components or composables: they register at priority 10 and auto-import is off. It sets its brand through these seams instead. Unset, each seam renders what Nuxt SEO renders.
+
+**Icon set.** Pick the set every semantic icon role renders from. The default is `hugeicons`. Install the matching `@iconify-json/<set>` collection. The icon aliases, the client bundle, and the server icon bundle follow the choice.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@nuxtseo/design-system'],
+  designSystem: { iconSet: 'lucide' },
+})
+```
+
+**Chart colours.** Every chart identity slot in `dataVizColors.ts` reads a `--ui-viz-<slot>` custom property: `clicks`, `impressions`, `ctr`, `position`, `sessions`, `users`, `pageviews`, `lcp`, `inp`, `cls`, `current`, `comparison`, `device-desktop`, `device-mobile`, `device-tablet`, `brand`, `non-brand`, `rank-1` to `rank-10`, `resource-document`, `resource-script`, `resource-stylesheet`, `resource-image`, `resource-font`, `category-1` to `category-5`, and `neutral`. The SVG paint, the `bg-viz-*` and `text-viz-*` classes, and the `/15` fills all follow it. Text classes use the same colour, so pick one that passes AA as text. Unset, light mode reads a deeper default for any slot whose stock hue falls under 3:1 on white; dark mode keeps the stock hue.
+
+```css
+:root {
+  --ui-viz-clicks: var(--ui-primary);
+  --ui-viz-neutral: #94a3b8;
+}
+```
+
+A palette `hex` field is a CSS colour, such as `var(--ui-viz-clicks, #3b82f6)`. Mix it with `color-mix()`; never parse it as hex.
+
+**Icon colour roles.** Add or remap a role that `getIconColor()` resolves. Write the classes in full, so Tailwind finds them in your source.
+
+```ts
+// app.config.ts
+export default defineAppConfig({
+  designSystem: {
+    iconColors: { lime: { bg: 'bg-lime-500/10', text: 'text-lime-500' } },
+  },
+})
+```
+
+**Motion.** The layer provides motion-v's `domAnimation` features to the whole app, `error.vue` included. A site needs no `<LazyMotion>` wrapper.