@nuxtseo/design-system 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,182 @@
-# 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:** `layers/brand`, which every Nuxt SEO app (`apps/site`, `apps/pro`, `apps/admin`, `apps/brand-kit`) extends in its place, 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+, `typescript` 5.8 to 6, `@nuxt/ui` 4.11+, `motion-v` 2.4+, `tailwindcss` 4.3+, and `zod` 4. The Vue SFC compiler resolves the layer's prop types through the TypeScript JS API, and TypeScript 7 has none.
+- The layer shares your copy of each peer, so the app runs one Nuxt UI, one Tailwind, one motion-v context, and one zod. pnpm and npm install a missing peer for you. You need no `overrides` for the layer.
+- 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, in Nitro too.
+- Write `app.config.ts` as a plain object. `defineAppConfig` is an auto-import, so the server bundle has no such function.
+- Import other modules by their path: `@nuxtseo/design-system/app/composables/formatting`. A directory with an `index.ts` imports by its name: `@nuxtseo/design-system/shared/icons`, `@nuxtseo/design-system/shared/contracts`, and `@nuxtseo/design-system/types`.
+- The layer ships no favicon and loads no fonts. Set both through the brand seams below.
+
+### 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-*`, `--font-*`, `--density-*`, and `--elevation-*`; never `--_depth-*` or `--_viz-*`. |
+| 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' },
+})
+```
+
+**Favicon.** The layer's favicon plugin emits a theme-aware icon link and an Apple touch icon link from `favicon` in `app.config.ts`. Unset, it emits neither. Each link's MIME type follows the file extension, so an SVG declares `image/svg+xml`. A mode without its own path uses the other mode's path. The links carry `id: 'favicon'` and `id: 'apple-touch-icon'`.
+
+```ts
+// app.config.ts
+export default {
+  favicon: {
+    light: '/icon-light.svg',
+    dark: '/icon-dark.svg',
+    appleTouchLight: '/touch-icon.png',
+    appleTouchDark: '/touch-icon-dark.png',
+  },
+}
+```
+
+**Type.** Set `--font-sans`, `--font-display`, `--font-title`, and `--font-mono` in your stylesheet, and register the faces with `fonts.families`. `--font-title` carries page titles (`.text-title` and the `font-title` utility). Its default is the display family. The layer self-hosts Nuxt SEO's Hubot Sans and Fira Code but registers neither by default, so no page preloads them. To use them, opt in:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@nuxtseo/design-system'],
+  designSystem: { fonts: true },
+})
+```
+
+**Own-site links.** An absolute HTTP or HTTPS prose link gets an external-link arrow. List the hosts that count as your site, and links to them get none. Unset, the layer lists no host.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  designSystem: { internalLinkHosts: ['example.com', 'www.example.com'] },
+})
+```
+
+**OG images.** [nuxt-og-image](https://nuxtseo.com/docs/og-image) compiles OG images against one Tailwind entry: the `#tailwindcss` alias, or else the first CSS entry that imports Tailwind, which is the layer's. Runtime `:root` overrides never reach it. To give OG images your theme, write an entry that imports the layer's stylesheet and restates your theme values. Then point the alias at it. Browsers never load this file.
+
+```css
+/* app/assets/css/og-theme.css */
+@import '@nuxtseo/design-system/css/global.css';
+
+@theme {
+  --font-sans: 'DM Sans', system-ui, sans-serif;
+  --font-display: 'Poppins', system-ui, sans-serif;
+  --font-title: 'Poppins', system-ui, sans-serif;
+}
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  alias: { '#tailwindcss': fileURLToPath(new URL('./app/assets/css/og-theme.css', import.meta.url)) },
+})
+```
+
+**Text and dashboard neutrals.** Three light mode text tokens sit on Nuxt SEO's violet hue, off the neutral ramp. The dashboard (`.dashboard-theme`) swaps the neutral ramp to mauve. Set these properties to re-hue them; never override the selectors. Unset, each keeps Nuxt SEO's value.
+
+| Property | Sets |
+| --- | --- |
+| `--ui-light-text`, `--ui-light-text-dimmed`, `--ui-light-text-highlighted` | `--ui-text`, `--ui-text-dimmed`, `--ui-text-highlighted` in light mode |
+| `--ui-dashboard-neutral-50` to `--ui-dashboard-neutral-950` | The dashboard's neutral ramp, both modes |
+| `--ui-dashboard-light-text-dimmed` | Dashboard `--ui-text-dimmed`, light mode |
+| `--ui-dashboard-dark-text-dimmed`, `--ui-dashboard-dark-text-muted` | Dashboard `--ui-text-dimmed` and `--ui-text-muted`, dark mode |
+
+```css
+:root {
+  --ui-light-text: var(--color-olive-800);
+  --ui-dashboard-neutral-50: var(--color-olive-50);
+  /* and each step to 950 */
+}
+```
+
+A `var()` inside a custom property resolves on the element that declares it. So `:root { --ui-dashboard-dark-text-muted: var(--ui-color-neutral-400) }` reads the marketing ramp's 400 step. Name a fixed colour or a `--color-*` step instead.
+
+**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. 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. Text classes use the mark colour unless `--ui-viz-<slot>-text` is set. If the mark colour fails AA as text, set it.
+
+```css
+:root {
+  --ui-viz-clicks: var(--ui-primary);
+  --ui-viz-neutral: #94a3b8;
+  --ui-viz-comparison: #a3a292;
+  --ui-viz-comparison-text: #67713a;
+}
+```
+
+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 {
+  designSystem: {
+    iconColors: { lime: { bg: 'bg-lime-500/10', text: 'text-lime-500' } },
+  },
+}
+```
+
+**Onboarding copy.** `UiOnboardingAnswers` takes an `intents` prop for the goal list and a `copy` prop for its strings: `roleQuestion`, `siteCountQuestion`, `seoExperienceQuestion`, `intentsQuestion`, `intentsHint`, `otherLabel`, and `otherPlaceholder`. Pass any of them. Unset keys keep the strings in `ONBOARDING_ANSWERS_COPY`. Onboarding Answers store the option ids, so the ids never change.
+
+**Motion.** The layer provides motion-v's `domAnimation` features to the whole app, `error.vue` included. A site needs no `<LazyMotion>` wrapper.