feat: unoCSS nuxt layer

[Maciej D (mdanilowicz)]

✨ Architectural Improvement: UnoCSS Design Tokens Layer

This branch introduces an important architectural change:
👉 UnoCSS design tokens have been extracted from @shopware/cms-base-layer and moved into a dedicated Nuxt layer:
@shopware/unocss-design-tokens-layer.

---

🧩 Why this change?

The cms-base-layer should stay focused on what it does best:

• 🧱 CMS rendering
• ♻️ Reusable storefront components

It should not own styling decisions or a design system.

Previously, keeping UnoCSS tokens inside cms-base-layer created tight coupling between:

• ⚙️ Functional CMS logic
• 🎨 Visual design choices

This meant every consumer of the CMS layer was implicitly forced to adopt styling decisions, which should instead be:

• optional
• composable
• explicit

---

🚀 What’s better now?

1. Clear separation of concerns

• 🧠 CMS logic → stays in cms-base-layer
• 🎨 Design tokens → live in a dedicated layer

---

2. More flexibility for Nuxt layers

Teams can now:

• ➕ Include the token layer
• 🔁 Replace it
• 🛠️ Extend it

➡️ All without modifying the CMS package

---

3. Explicit styling dependencies

• ❌ No more hidden styling side effects
• ✅ Consumers (e.g. vue-starter-template) define styling consciously

---

🛠️ Maintainability improvements

• 📦 Centralized UnoCSS tokens (no duplication across templates)
• 🔄 Easier updates and theme changes
• 🧼 Cleaner architecture in layered storefronts

The updated vue-starter-template now:

• extends the dedicated token layer
• merges its local UnoCSS config with the base layer config

➡️ This is a scalable and clean pattern for layered projects.

---

🔍 Improved predictability

Previously:

• ⚠️ Some styling relied on runtime UnoCSS behavior in cms-base-layer
• 🤯 This could introduce hidden complexity

Now:

• 📍 Design tokens have a clear, single source of truth
• 🧩 CMS layer becomes more framework-neutral in terms of styling

---

🧠 In short

This change makes the codebase:

• 🧩 More modular
• 🪶 Easier to extend
• 🛠️ Easier to maintain
• 🏗️ Better aligned with layered architecture principles

---

A small structural change — but a big step toward a cleaner and more scalable frontend architecture 🚀

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
frontends-starter-template-extended	Ready	Preview, Comment	Apr 29, 2026 9:45am
frontends-vue-starter-template	Ready	Preview, Comment	Apr 29, 2026 9:45am
old-frontends-demo	Ready	Preview, Comment	Apr 29, 2026 9:45am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
shopware-frontends-docs	Skipped		Apr 29, 2026 9:45am

[Copilot]

Pull request overview

Introduces a new Nuxt layer (@shopware/unocss-design-tokens-layer) to decouple UnoCSS design tokens and UnoCSS runtime behavior from @shopware/cms-base-layer, updating templates and docs to consume styling defaults via the new layer.

Changes:

• Added @shopware/unocss-design-tokens-layer package containing UnoCSS token config + UnoCSS runtime plugin + Nuxt layer config.
• Updated vue-starter-template (and docs) to extend the new design-tokens layer and removed token definitions from the template’s local Uno config.
• Removed UnoCSS config/theme artifacts and UnoCSS dependencies/config surface from @shopware/cms-base-layer.

Reviewed changes

Copilot reviewed 28 out of 31 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
templates/vue-starter-template/uno.config.ts	Removes in-template token palette, leaving only template-specific overrides/extensions.
templates/vue-starter-template/package.json	Adds dependency on @shopware/unocss-design-tokens-layer.
templates/vue-starter-template/nuxt.config.ts	Extends the new design-tokens layer.
templates/vue-starter-template/README.md	Updates styling/layering explanation to mention the new layer.
templates/vue-demo-store/uno.config.ts	Adds explicit presets and reintroduces some CMS token colors in template config.
pnpm-lock.yaml	Lockfile updates to reflect dependency graph changes and new workspace package.
packages/unocss-design-tokens-layer/uno.config.ts	New shared design-token color palette + preset baseline.
packages/unocss-design-tokens-layer/tsconfig.json	TypeScript config for the new layer package.
packages/unocss-design-tokens-layer/src/index.ts	Placeholder entrypoint for build output.
packages/unocss-design-tokens-layer/package.json	New package manifest for the Nuxt layer.
packages/unocss-design-tokens-layer/nuxt.config.ts	Layer-level UnoCSS module/reset/config defaults.
packages/unocss-design-tokens-layer/index.d.ts	Nuxt AppConfig type augmentation stub for the new layer.
packages/unocss-design-tokens-layer/build.config.ts	Unbuild configuration for producing dist artifacts.
packages/unocss-design-tokens-layer/biome.json	Biome config inheriting repo defaults.
packages/unocss-design-tokens-layer/app/plugins/unocss-runtime.client.ts	New client plugin to initialize UnoCSS runtime for dynamic classes.
packages/unocss-design-tokens-layer/app/.gitkeep	Keeps app/ directory in source control.
packages/unocss-design-tokens-layer/README.md	Documents intended usage/customization of the new layer.
packages/cms-base-layer/uno.config.ts	Removes UnoCSS config from CMS base layer (deleted).
packages/cms-base-layer/package.json	Drops UnoCSS-related dependencies from CMS base layer.
packages/cms-base-layer/index.d.ts	Removes unocssRuntime from CMS base layer AppConfig type.
packages/cms-base-layer/app/utils/unocss-theme.ts	Removes CMS layer Uno theme definition (deleted).
packages/cms-base-layer/app/composables/useTypedAppConfig.ts	Removes unocssRuntime from typed app config return type.
packages/cms-base-layer/app/app.config.ts	Removes default unocssRuntime: true from CMS layer app config.
packages/cms-base-layer/README.md	Updates docs to reflect styling tokens/runtime now living in the new layer.
packages/cms-base-layer/AGENTS.md	Updates AI-assistant guidance to reflect decoupled styling concerns.
apps/docs/src/resources/troubleshooting.md	Updates troubleshooting snippet to include the new layer in extends.
apps/docs/src/getting-started/templates/vue-starter-template.md	Documents the new layer in template composition and Uno config guidance.
apps/docs/src/getting-started/templates/vue-starter-template-extended.md	Updates extended template docs to match new “extend base Uno config” pattern.
apps/docs/src/framework/styling.md	Updates styling docs to describe the layered setup (CMS vs tokens).
apps/docs/src/framework/shopping-experiences.md	Updates Shopping Experiences guide to mention new layer and configuration.
apps/docs/src/framework/design-tokens.md	Updates token docs to reference the new layer as the source of truth.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (3)

packages/unocss-design-tokens-layer/app/plugins/unocss-runtime.client.ts:20

• initUnocssRuntime is executed at module load (line 5) and again inside the plugin (line 19). This causes side effects even when the runtime is disabled and can register duplicate MutationObservers. Move initialization entirely inside the defineNuxtPlugin callback and ensure it runs only once when enabled.
  packages/unocss-design-tokens-layer/app/plugins/unocss-runtime.client.ts:18
• The enable/disable check currently uses if (!appConfig.unocssRuntime) return;, which disables the runtime when unocssRuntime is undefined. This contradicts the docs stating it’s enabled by default. Consider treating it as enabled unless explicitly set to false, or add an app.config.ts in this layer that sets unocssRuntime: true by default.
  packages/unocss-design-tokens-layer/app/plugins/unocss-runtime.client.ts:16
• Leftover console.log in a Nuxt plugin will spam production client logs and can leak implementation details. Please remove this debug logging (or gate it behind a dev-only flag).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.