feat(design): unify built-in plugins on a shared @internal/design system

The git (React/Next), terminals (Svelte) and code-server (vanilla DOM)
plugins each shipped their own styling engine, palette and components, so
they read as three different products. Introduce a single, framework-neutral
design system the built-in plugins extend, so they look and feel like one
product everywhere.

- Add @internal/design (private): one `presetDevframe()` UnoCSS preset
  (presetWind4 + presetIcons + directive/variant-group transformers + the
  semantic token theme + the shared `df-*` component vocabulary), the
  `--df-*` token values in theme.css (light/dark), and a prebuilt stylesheet
  for non-UnoCSS consumers.
- Migrate terminals and code-server onto the shared preset + `df-*` classes.
- Migrate git from Tailwind v4 + shadcn to UnoCSS driven by the same tokens.
- Wire the package into alias/tsconfig/turbo and document the convention.

Author: antfubot

AGENTS.md

@@ -38,6 +38,15 @@ The `pnpm test` script intentionally runs `build` first so `tsnapi` snapshots co
 - Utility imports use the package-path form `devframe/utils/*`, never relative `../utils/*`.
 - Dependencies go through the pnpm catalogs in `pnpm-workspace.yaml` (`cli`, `inlined`, `testing`, `types`) — add to a catalog and reference as `catalog:<name>`, don't pin versions in `package.json`.
 
+### Design system
+
+The built-in plugins share one design system, `@internal/design`, so they look and feel like one product across frameworks (the Git dashboard is React/Next, terminals is Svelte, code-server is vanilla DOM). It's an optional package plugins opt into — devframe core stays headless and ships no styling.
+
+- **One preset to extend.** Each plugin's `uno.config.ts` is just `presets: [presetDevframe()]` (imported from `@internal/design/preset`). The preset bundles `presetWind4` + `presetIcons` + the directive/variant-group transformers, the semantic token theme, and the shared `df-*` component shortcuts. Don't re-declare presets, palettes, or shortcuts per plugin.
+- **One token source.** Import `@internal/design/theme.css` once on the page (after the generated UnoCSS stylesheet so its base layer wins). Token *values* (the `--df-*` custom properties, light + dark via the `.dark` class) live only there — never hardcode a palette in a plugin.
+- **Shared component vocabulary.** Build UI from the `df-*` classes (`df-btn`, `df-badge`, `df-tab`, `df-navtab`, `df-card`, `df-input`, `df-dot`, `df-tag-*`, …) and the semantic token utilities (`bg-primary`, `text-muted-foreground`, `bg-card`, `border-border`, …). Markup differs per framework; the classes resolve identically, which is what keeps the surfaces consistent. Non-UnoCSS consumers can link the prebuilt `@internal/design/style.css`.
+- **Plain `.ts`/vanilla views** must opt `.ts` into UnoCSS extraction (`content.pipeline.include`), since UnoCSS only scans framework files by default.
+
 ### Devframe design principles
 
 These reinforce devframe's positioning as "the container for one devtool integration, portable to multiple viewers". When in doubt, err on the side of "devframe provides primitives, the hub provides UX".

alias.ts

@@ -45,6 +45,10 @@ export const alias = {
   '@devframes/hub': r('hub/src/index.ts'),
   '@devframes/nuxt/runtime/plugin.client': r('nuxt/src/runtime/plugin.client.ts'),
   '@devframes/nuxt': r('nuxt/src/index.ts'),
+  '@internal/design/preset': r('design/src/preset.ts'),
+  '@internal/design/tokens': r('design/src/tokens.ts'),
+  '@internal/design/theme.css': r('design/src/theme.css'),
+  '@internal/design': r('design/src/index.ts'),
   '@devframes/plugin-code-server/client': p('code-server/src/client/index.ts'),
   '@devframes/plugin-code-server/node': p('code-server/src/node/index.ts'),
   '@devframes/plugin-code-server/constants': p('code-server/src/constants.ts'),
@@ -65,11 +69,14 @@ export const alias = {
   'devframe': r('devframe/src'),
 }
 
-// update tsconfig.base.json
+// update tsconfig.base.json — CSS aliases exist for Vite resolution only;
+// TypeScript resolves `*.css` side-effect imports through ambient shims.
 const raw = fs.readFileSync(join(root, 'tsconfig.base.json'), 'utf-8').trim()
 const tsconfig = JSON.parse(raw)
 tsconfig.compilerOptions.paths = Object.fromEntries(
-  Object.entries(alias).map(([key, value]) => [key, [`./${relative(root, value)}`]]),
+  Object.entries(alias)
+    .filter(([key]) => !key.endsWith('.css'))
+    .map(([key, value]) => [key, [`./${relative(root, value)}`]]),
 )
 const newRaw = JSON.stringify(tsconfig, null, 2)
 if (newRaw !== raw)

packages/design/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@internal/design",
+  "type": "module",
+  "version": "0.5.4",
+  "private": true,
+  "description": "Internal, unpublished design system for devframe's built-in plugins — one UnoCSS preset, one token set, one shared component vocabulary, portable across frameworks.",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./preset": "./dist/preset.mjs",
+    "./tokens": "./dist/tokens.mjs",
+    "./theme.css": "./dist/theme.css",
+    "./style.css": "./dist/style.css",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown && tsx scripts/build-css.ts",
+    "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "prepack": "pnpm run build"
+  },
+  "peerDependencies": {
+    "unocss": "^66.0.0"
+  },
+  "dependencies": {
+    "@iconify-json/ph": "catalog:frontend"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:types",
+    "tsdown": "catalog:build",
+    "tsx": "catalog:build",
+    "unocss": "catalog:frontend"
+  }
+}

packages/design/scripts/build-css.ts

@@ -0,0 +1,48 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { createGenerator } from 'unocss'
+import { presetDevframe, shortcuts } from '../src/preset'
+
+/**
+ * Emit the design package's shipped CSS:
+ *
+ * - `dist/theme.css` — the `--df-*` token values + base layer, verbatim.
+ * - `dist/style.css` — a standalone stylesheet (UnoCSS preflights + every
+ *   `df-*` component class + the tokens) for consumers that don't run UnoCSS
+ *   themselves but still want the shared component vocabulary.
+ */
+
+const root = fileURLToPath(new URL('..', import.meta.url))
+const distDir = resolve(root, 'dist')
+
+async function main(): Promise<void> {
+  await mkdir(distDir, { recursive: true })
+
+  const theme = await readFile(resolve(root, 'src/theme.css'), 'utf8')
+  await writeFile(resolve(distDir, 'theme.css'), theme)
+
+  // Materialize every named `df-*` shortcut (and a few palette tags) so the
+  // standalone stylesheet carries the full shared component vocabulary.
+  const names = new Set<string>()
+  for (const entry of shortcuts) {
+    if (Array.isArray(entry))
+      continue
+    for (const key of Object.keys(entry))
+      names.add(key)
+  }
+  for (const color of ['blue', 'amber', 'green', 'red', 'sky', 'violet', 'rose'])
+    names.add(`df-tag-${color}`)
+
+  const generator = await createGenerator({ presets: [presetDevframe()] })
+  const { css } = await generator.generate(names, { preflights: true })
+
+  const banner = '/* @internal/design — prebuilt stylesheet. Generated by scripts/build-css.ts; do not edit. */\n'
+  await writeFile(resolve(distDir, 'style.css'), `${banner}${css}\n${theme}`)
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

packages/design/src/index.ts

@@ -0,0 +1,13 @@
+export { presetDevframe, shortcuts } from './preset'
+export type { PresetDevframeOptions } from './preset'
+export { presetDevframe as default } from './preset'
+export {
+  cssVar,
+  PAIRED_TOKENS,
+  radius,
+  SOLO_TOKENS,
+  TOKEN_PREFIX,
+  tokenColors,
+} from './tokens'
+
+export type { DesignToken, PairedToken, SoloToken } from './tokens'

packages/design/src/preset.ts

@@ -0,0 +1,141 @@
+import type { Preset } from 'unocss'
+import {
+  definePreset,
+  presetIcons,
+  presetWind4,
+  transformerDirectives,
+  transformerVariantGroup,
+} from 'unocss'
+import { radius, tokenColors } from './tokens'
+
+export interface PresetDevframeOptions {
+  /**
+   * Options forwarded to `presetIcons`. The default icon scale matches the
+   * inline-with-text sizing used across the built-in plugins.
+   */
+  icons?: Parameters<typeof presetIcons>[0]
+}
+
+/**
+ * The shared `df-*` component vocabulary. These shortcuts are the cross-frame
+ * "components": markup differs per framework (React, Svelte, vanilla DOM) but a
+ * `df-btn df-btn-primary` button — or a `df-badge`, `df-tab`, `df-card`, … —
+ * resolves to the same CSS everywhere, so they look and feel identical. The
+ * definitions mirror the flagship shadcn/ui primitives so a hand-written
+ * `df-btn` and a generated `<Button>` are visually interchangeable.
+ */
+export const shortcuts = [
+  {
+    // Foundations — friendly aliases onto the semantic token palette.
+    'bg-base': 'bg-background',
+    'color-base': 'text-foreground',
+    'border-base': 'border-border',
+    'bg-active': 'bg-accent',
+    'color-active': 'text-primary',
+    'border-active': 'border-primary/40',
+    'op-fade': 'op65 dark:op75',
+    'op-mute': 'op40 dark:op45',
+
+    // Named depth layers so chrome stacks predictably.
+    'z-toolbar': 'z-20',
+    'z-nav': 'z-30',
+
+    // Buttons.
+    'df-btn': 'inline-flex items-center justify-center gap-2 shrink-0 whitespace-nowrap select-none cursor-pointer rounded-md text-sm font-medium h-9 px-4 py-2 outline-none transition-colors [&_svg]:pointer-events-none [&_svg]:shrink-0 disabled:(pointer-events-none op50) focus-visible:(ring-[3px] ring-ring/50)',
+    'df-btn-primary': 'bg-primary text-primary-foreground shadow-xs hover:bg-primary/90',
+    'df-btn-secondary': 'bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80',
+    'df-btn-outline': 'border border-border bg-background shadow-xs hover:(bg-accent text-accent-foreground)',
+    'df-btn-ghost': 'hover:(bg-accent text-accent-foreground)',
+    'df-btn-destructive': 'bg-destructive text-white shadow-xs hover:bg-destructive/90',
+    'df-btn-link': 'text-primary underline-offset-4 hover:underline',
+    // Size modifiers override the base size with `!` so they win regardless of
+    // stylesheet order — no `tailwind-merge` needed in Svelte/vanilla markup.
+    'df-btn-sm': 'h-8! gap-1.5! px-3!',
+    'df-btn-lg': 'h-10! px-6!',
+    'df-btn-icon': 'w-9! px-0!',
+    'df-btn-icon-sm': 'h-7! w-7! px-0!',
+
+    // Badges (solid / semantic) and soft tags share a silhouette.
+    'df-badge': 'inline-flex items-center justify-center gap-1 w-fit shrink-0 whitespace-nowrap rounded-md border px-2 py-0.5 text-xs font-medium',
+    'df-badge-primary': 'df-badge border-transparent bg-primary text-primary-foreground',
+    'df-badge-secondary': 'df-badge border-transparent bg-secondary text-secondary-foreground',
+    'df-badge-success': 'df-badge border-success/20 bg-success/15 text-success',
+    'df-badge-warning': 'df-badge border-warning/20 bg-warning/15 text-warning',
+    'df-badge-destructive': 'df-badge border-transparent bg-destructive text-white',
+    'df-badge-outline': 'df-badge text-foreground',
+
+    // Segmented tabs (mirror the shadcn segmented control).
+    'df-tabs-list': 'inline-flex items-center justify-center w-fit h-9 p-[3px] rounded-lg bg-muted text-muted-foreground',
+    'df-tab': 'inline-flex flex-1 items-center justify-center gap-1.5 h-[calc(100%-1px)] px-2 py-1 rounded-md border border-transparent text-sm font-medium whitespace-nowrap select-none cursor-pointer outline-none transition-colors disabled:(pointer-events-none op50) focus-visible:(ring-[3px] ring-ring/50) data-[state=active]:(bg-background text-foreground shadow-sm)',
+
+    // Closeable navigation tabs (e.g. terminal sessions, open documents).
+    'df-navtab': 'relative inline-flex items-center gap-1.5 max-w-52 px-2 py-1 rounded-md border border-transparent text-sm op-fade select-none cursor-pointer transition-colors hover:(op100 bg-accent)',
+    'df-navtab-active': 'op100! bg-accent border-base! color-base',
+
+    // Surfaces.
+    'df-card': 'flex flex-col rounded-xl border border-border bg-card text-card-foreground shadow-sm',
+    'df-panel': 'rounded-lg border border-border bg-card text-card-foreground',
+
+    // Form controls.
+    'df-input': 'flex w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-xs outline-none transition-colors placeholder:text-muted-foreground disabled:(cursor-not-allowed op50) focus-visible:(border-ring ring-[3px] ring-ring/50)',
+
+    // Links.
+    'df-link': 'text-primary underline-offset-4 hover:underline',
+
+    // Status dots — real lifecycle states only.
+    'df-dot': 'inline-block h-1.5 w-1.5 rounded-full shrink-0',
+    'df-dot-running': 'bg-success',
+    'df-dot-idle': 'bg-muted-foreground',
+    'df-dot-error': 'bg-destructive',
+
+    // Indeterminate spinner.
+    'df-spinner': 'inline-block size-4 rounded-full border-2 border-current border-t-transparent animate-spin',
+  },
+
+  // Soft, palette-driven tags: `df-tag-blue`, `df-tag-amber`, … for ad-hoc
+  // categorical labels that fall outside the semantic palette.
+  [
+    /^df-tag-(\w+)$/,
+    ([, color]: string[]) =>
+      `inline-flex items-center gap-1 w-fit whitespace-nowrap rounded-md border px-2 py-0.5 text-xs font-medium border-${color}-500/20 bg-${color}-400/15 text-${color}-700 dark:text-${color}-300`,
+  ] as [RegExp, (match: string[]) => string],
+]
+
+/**
+ * The single UnoCSS preset every devframe plugin extends. It bundles
+ * `presetWind4` (Tailwind-compatible utilities + class-based `dark:`),
+ * `presetIcons` (Phosphor via `@iconify-json/ph`), the directive + variant-group
+ * transformers, the semantic token theme, and the shared `df-*` shortcuts.
+ *
+ * A plugin's entire `uno.config.ts` becomes:
+ *
+ * ```ts
+ * import { presetDevframe } from '@internal/design/preset'
+ * import { defineConfig } from 'unocss'
+ *
+ * export default defineConfig({ presets: [presetDevframe()] })
+ * ```
+ *
+ * Pair it with `import '@internal/design/theme.css'` once on the page to define
+ * the `--df-*` token values and base element styling.
+ */
+export function presetDevframe(options: PresetDevframeOptions = {}): Preset {
+  return definePreset({
+    name: '@internal/design/preset',
+    theme: {
+      colors: tokenColors,
+      radius,
+    },
+    shortcuts,
+    presets: [
+      presetWind4(),
+      presetIcons({ scale: 1.1, ...options.icons }),
+    ],
+    transformers: [
+      transformerDirectives(),
+      transformerVariantGroup(),
+    ],
+  })
+}
+
+export default presetDevframe