@utopia-studio-design/design-system-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Utopia Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @utopia-studio-design/design-system-cli
+
+CLI for installing, inspecting, and validating the Utopia Studio design system. The CLI doubles as an AI-agent entrypoint: it creates agent docs, prints token data, installs component templates, and checks whether component manifests include the props, anatomy, states, slots, examples, and agent contract fields required for safe UI generation.
+
+```sh
+npx @utopia-studio-design/design-system-cli init
+npx @utopia-studio-design/design-system-cli add button
+npx @utopia-studio-design/design-system-cli tokens
+npx @utopia-studio-design/design-system-cli agent-docs
+npx @utopia-studio-design/design-system-cli doctor
+```
+
+The binary name is `utopia-ds`.
+
+## Doctor Checks
+
+`utopia-ds doctor` verifies dependencies, CSS tokens, square-radius compliance, component manifest completeness, component `agentContract` completeness, theme manifest completeness, source-example docs, and the AI entrypoint:
+
+AI docs checks:
+
+- `docs/design-system/examples.md`
+- `public/llms.txt` references `docs/design-system/examples.md`
+
+Component checks:
+
+- `props`
+- `anatomy`
+- `states`
+- `slots`
+- `examples`
+- `aiRules`
+
+Agent contract checks:
+
+- `useWhen`
+- `avoidWhen`
+- `fallbackToShadcn`
+- `requiredTokens`
+- `neverInvent`
+- `validationChecklist`
+
+Theme checks:
+
+- `defaultTheme`
+- `semanticRoles`
+- default theme values for every semantic role

package/bin/utopia-ds.mjs

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const cliRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const templateRoot = join(cliRoot, 'templates')
+const args = process.argv.slice(2)
+
+function argValue(name, fallback) {
+  const index = args.indexOf(name)
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback
+}
+
+const cwd = resolve(argValue('--cwd', process.cwd()))
+const command = args.find((arg) => !arg.startsWith('--')) ?? '--help'
+
+function ensureDir(path) {
+  mkdirSync(path, { recursive: true })
+}
+
+function copyTemplate(from, to) {
+  ensureDir(dirname(to))
+  copyFileSync(join(templateRoot, from), to)
+  console.log(`created ${to}`)
+}
+
+function readTemplate(path) {
+  return readFileSync(join(templateRoot, path), 'utf8')
+}
+
+function help() {
+  console.log(`Utopia Design System CLI
+
+Usage:
+  utopia-ds init [--cwd path]
+  utopia-ds add <component> [--cwd path]
+  utopia-ds tokens
+  utopia-ds agent-docs [--cwd path]
+  utopia-ds doctor [--cwd path]
+
+Components:
+  button, icon-button, button-group, card, badge, tooltip, page-hero,
+  cta-section, brand-action, topbar
+
+Agent contract:
+  Components should define useWhen, avoidWhen, fallbackToShadcn,
+  requiredTokens, neverInvent, and validationChecklist.
+
+Themes:
+  Utopia is the default/reference theme. Themeable apps/templates
+  should map all visual decisions through semantic roles.
+`)
+}
+
+function init() {
+  copyTemplate('styles/tokens.css', join(cwd, 'src/styles/utopia-tokens.css'))
+  copyTemplate('styles/styles.css', join(cwd, 'src/styles/utopia-styles.css'))
+  copyTemplate('lib/utils.ts', join(cwd, 'src/lib/utils.ts'))
+  console.log('Add `import "./styles/utopia-styles.css"` to your app entrypoint.')
+}
+
+function add() {
+  const component = args[1]
+  const componentMap = {
+    button: 'button.tsx',
+    'icon-button': 'icon-button.tsx',
+    'button-group': 'button-group.tsx',
+    card: 'card.tsx',
+    badge: 'badge.tsx',
+    tooltip: 'tooltip.tsx',
+    'page-hero': 'page-hero.tsx',
+    'cta-section': 'cta-section.tsx',
+    'brand-action': 'brand-action.tsx',
+    topbar: 'topbar.tsx',
+  }
+  const componentDependencies = {
+    'icon-button': ['button', 'tooltip'],
+    'button-group': ['button'],
+    'page-hero': ['brand-action'],
+    'cta-section': ['brand-action'],
+    topbar: ['button'],
+  }
+
+  if (!component || !componentMap[component]) {
+    throw new Error(`Unknown component "${component ?? ''}". Run utopia-ds --help for available components.`)
+  }
+
+  const componentsToCopy = new Set()
+  const queue = [component]
+
+  while (queue.length) {
+    const next = queue.shift()
+
+    for (const dependency of componentDependencies[next] ?? []) {
+      if (!componentsToCopy.has(dependency)) queue.push(dependency)
+    }
+
+    componentsToCopy.add(next)
+  }
+
+  for (const componentName of componentsToCopy) {
+    copyTemplate(`components/${componentMap[componentName]}`, join(cwd, `src/components/utopia/${componentMap[componentName]}`))
+  }
+
+  copyTemplate('lib/utils.ts', join(cwd, 'src/lib/utils.ts'))
+}
+
+function tokens() {
+  process.stdout.write(readTemplate('tokens.json'))
+}
+
+function agentDocs() {
+  copyTemplate('agent-docs/index.md', join(cwd, 'docs/design-system/agent-docs/index.md'))
+  copyTemplate('agent-docs/examples.md', join(cwd, 'docs/design-system/examples.md'))
+  copyTemplate('agent-docs/llms.txt', join(cwd, 'public/llms.txt'))
+}
+
+function doctor() {
+  const packageJsonPath = join(cwd, 'package.json')
+  const packageJson = existsSync(packageJsonPath) ? JSON.parse(readFileSync(packageJsonPath, 'utf8')) : {}
+  const deps = { ...(packageJson.dependencies ?? {}), ...(packageJson.devDependencies ?? {}) }
+  const warnings = []
+
+  for (const dep of ['react', 'class-variance-authority', 'radix-ui']) {
+    if (!deps[dep]) warnings.push(`Missing dependency: ${dep}`)
+  }
+
+  const candidateCssFiles = [
+    join(cwd, 'src/index.css'),
+    join(cwd, 'src/app/globals.css'),
+    join(cwd, 'src/styles/utopia-tokens.css'),
+  ]
+  const css = candidateCssFiles.filter(existsSync).map((file) => readFileSync(file, 'utf8')).join('\n')
+  for (const token of ['--background', '--primary', '--font-sans', '--radius']) {
+    if (!css.includes(token)) warnings.push(`Missing CSS token: ${token}`)
+  }
+
+  if (css.includes('border-radius: 16px') || css.includes('--radius: 16px')) {
+    warnings.push('Found 16px radius. Utopia DS expects square geometry.')
+  }
+
+  const manifestCandidates = [
+    join(cwd, 'packages/design-system/src/manifests/components.json'),
+    join(cwd, 'src/manifests/components.json'),
+    join(cwd, 'node_modules/@utopia-studio-design/design-system/components.json'),
+  ]
+  const manifestPath = manifestCandidates.find(existsSync)
+  const requiredAgentContractFields = [
+    'useWhen',
+    'avoidWhen',
+    'fallbackToShadcn',
+    'requiredTokens',
+    'neverInvent',
+    'validationChecklist',
+  ]
+
+  if (!manifestPath) {
+    warnings.push('Missing components manifest with agent contracts.')
+  } else {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+    const components = Array.isArray(manifest.components) ? manifest.components : []
+
+    if (!components.length) {
+      warnings.push('Components manifest has no components.')
+    }
+
+    for (const component of components) {
+      for (const field of ['props', 'anatomy', 'states', 'slots', 'examples', 'aiRules']) {
+        if (!Array.isArray(component[field]) || component[field].length === 0) {
+          warnings.push(`Incomplete component ${field}: ${component.name ?? 'unknown component'}`)
+        }
+      }
+
+      const contract = component.agentContract
+      if (!contract) {
+        warnings.push(`Missing agentContract: ${component.name ?? 'unknown component'}`)
+        continue
+      }
+
+      for (const field of requiredAgentContractFields) {
+        if (!Array.isArray(contract[field]) || contract[field].length === 0) {
+          warnings.push(`Incomplete agentContract.${field}: ${component.name ?? 'unknown component'}`)
+        }
+      }
+    }
+  }
+
+  const themeManifestCandidates = [
+    join(cwd, 'packages/design-system/src/manifests/themes.json'),
+    join(cwd, 'src/manifests/themes.json'),
+    join(cwd, 'node_modules/@utopia-studio-design/design-system/themes.json'),
+  ]
+  const themeManifestPath = themeManifestCandidates.find(existsSync)
+  const requiredThemeRoles = [
+    'background',
+    'foreground',
+    'card',
+    'cardForeground',
+    'primary',
+    'primaryForeground',
+    'secondary',
+    'secondaryForeground',
+    'muted',
+    'mutedForeground',
+    'border',
+    'input',
+    'ring',
+    'radius',
+  ]
+
+  if (!themeManifestPath) {
+    warnings.push('Missing themes manifest.')
+  } else {
+    const themeManifest = JSON.parse(readFileSync(themeManifestPath, 'utf8'))
+    const defaultTheme = themeManifest.defaultTheme
+    const themes = Array.isArray(themeManifest.themes) ? themeManifest.themes : []
+    const selectedTheme = themes.find((theme) => theme.id === defaultTheme)
+    const semanticRoles = Array.isArray(themeManifest.semanticRoles) ? themeManifest.semanticRoles : []
+    const roleNames = new Set(semanticRoles.map((role) => role.name))
+
+    if (!defaultTheme) warnings.push('themes.json missing defaultTheme.')
+    if (!selectedTheme) warnings.push(`themes.json missing default theme entry: ${defaultTheme ?? 'unknown'}`)
+
+    for (const role of requiredThemeRoles) {
+      if (!roleNames.has(role)) warnings.push(`themes.json missing semantic role: ${role}`)
+      if (selectedTheme && !(role in (selectedTheme.values ?? {}))) {
+        warnings.push(`Default theme missing value for role: ${role}`)
+      }
+    }
+
+    const plannedThemeSlots = Array.isArray(themeManifest.plannedThemeSlots) ? themeManifest.plannedThemeSlots : []
+    if (!plannedThemeSlots.length) warnings.push('themes.json missing plannedThemeSlots.')
+
+    for (const slot of plannedThemeSlots) {
+      for (const field of ['sourceTemplates', 'recommendedComponents', 'roleGuidance', 'validationChecklist']) {
+        if (!Array.isArray(slot[field]) || slot[field].length === 0) {
+          warnings.push(`Theme slot ${slot.id ?? 'unknown'} missing ${field}.`)
+        }
+      }
+    }
+
+    const themeAuthoring = themeManifest.themeAuthoring ?? {}
+    for (const field of ['readOrder', 'newThemeChecklist', 'doNot']) {
+      if (!Array.isArray(themeAuthoring[field]) || themeAuthoring[field].length === 0) {
+        warnings.push(`themes.json missing themeAuthoring.${field}.`)
+      }
+    }
+
+    if (!themeAuthoring.requiredDecision) warnings.push('themes.json missing themeAuthoring.requiredDecision.')
+  }
+
+  const siteExamplesCandidates = [
+    join(cwd, 'packages/design-system/src/manifests/site-examples.json'),
+    join(cwd, 'src/manifests/site-examples.json'),
+    join(cwd, 'node_modules/@utopia-studio-design/design-system/site-examples.json'),
+  ]
+  const siteExamplesPath = siteExamplesCandidates.find(existsSync)
+
+  if (!siteExamplesPath) {
+    warnings.push('Missing site examples manifest.')
+  } else {
+    const siteExamples = JSON.parse(readFileSync(siteExamplesPath, 'utf8'))
+    for (const collection of ['sourceRoutes', 'badges', 'cards', 'heroes', 'ctas']) {
+      if (!Array.isArray(siteExamples[collection]) || siteExamples[collection].length === 0) {
+        warnings.push(`site-examples.json missing collection: ${collection}`)
+      }
+    }
+  }
+
+  const examplesDocPath = join(cwd, 'docs/design-system/examples.md')
+  const llmsPath = join(cwd, 'public/llms.txt')
+
+  if (!existsSync(examplesDocPath)) {
+    warnings.push('Missing docs/design-system/examples.md source-example summary.')
+  }
+
+  if (!existsSync(llmsPath)) {
+    warnings.push('Missing public/llms.txt AI entrypoint.')
+  } else {
+    const llms = readFileSync(llmsPath, 'utf8')
+    if (!llms.includes('docs/design-system/examples.md')) {
+      warnings.push('public/llms.txt does not reference docs/design-system/examples.md.')
+    }
+  }
+
+  const templateManifestCandidates = [
+    join(cwd, 'packages/design-system/src/manifests/templates.json'),
+    join(cwd, 'src/manifests/templates.json'),
+    join(cwd, 'node_modules/@utopia-studio-design/design-system/templates.json'),
+  ]
+  const templateManifestPath = templateManifestCandidates.find(existsSync)
+
+  if (!templateManifestPath) {
+    warnings.push('Missing templates manifest.')
+  } else {
+    const templateManifest = JSON.parse(readFileSync(templateManifestPath, 'utf8'))
+    const templates = Array.isArray(templateManifest.templates) ? templateManifest.templates : []
+
+    if (!templates.length) warnings.push('templates.json has no templates.')
+
+    for (const template of templates) {
+      for (const field of ['id', 'title', 'purpose', 'aiPrompt']) {
+        if (!template[field]) warnings.push(`Template missing ${field}: ${template.id ?? 'unknown template'}`)
+      }
+
+      for (const field of ['requiredSections', 'componentStack', 'bestPractices', 'validationChecklist']) {
+        if (!Array.isArray(template[field]) || template[field].length === 0) {
+          warnings.push(`Template ${template.id ?? 'unknown template'} missing ${field}.`)
+        }
+      }
+    }
+  }
+
+  if (warnings.length) {
+    console.log('Utopia DS doctor warnings:')
+    for (const warning of warnings) console.log(`- ${warning}`)
+    process.exitCode = 1
+    return
+  }
+
+  console.log('Utopia DS doctor passed.')
+}
+
+try {
+  switch (command) {
+    case '--help':
+    case 'help':
+      help()
+      break
+    case 'init':
+      init()
+      break
+    case 'add':
+      add()
+      break
+    case 'tokens':
+      tokens()
+      break
+    case 'agent-docs':
+      agentDocs()
+      break
+    case 'doctor':
+      doctor()
+      break
+    default:
+      help()
+      process.exitCode = 1
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error)
+  process.exitCode = 1
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@utopia-studio-design/design-system-cli",
+  "version": "0.1.0",
+  "description": "CLI for installing, inspecting, and validating the Utopia Studio design system.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "utopia-ds": "bin/utopia-ds.mjs"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node bin/utopia-ds.mjs --help",
+    "check": "node bin/utopia-ds.mjs tokens > /tmp/utopia-ds-tokens.json && node bin/utopia-ds.mjs doctor --cwd ../..",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "@utopia-studio-design/design-system": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18.18"
+  }
+}

package/templates/agent-docs/examples.md

@@ -0,0 +1,33 @@
+# Site Examples
+
+Use this page as the human-readable companion to `site-examples.json`.
+
+## Source
+
+- Prefer `packages/design-system/src/manifests/site-examples.json` when it exists in the app.
+- If the manifest is installed through the package, read `node_modules/@utopia-studio-design/design-system/site-examples.json`.
+- Use this document as an index for humans and AI agents; keep detailed examples source-driven.
+
+## Rules
+
+- Use real Utopia sample copy before inventing placeholder content.
+- Preserve `sourceRoute` and source file references when generating docs or UI examples.
+- Use examples for content shape, tone, and component fit only.
+- Use `tokens.json`, `themes.json`, `components.json`, and `patterns.json` for design rules.
+
+## Expected Collections
+
+- `sourceRoutes`: route labels, hrefs, and source files.
+- `badges`: status and taxonomy labels with variants.
+- `cards`: Card-ready examples with eyebrow, title, body, href, source route, and component fit.
+- `heroes`: PageHero-ready examples with actions.
+- `ctas`: CtaSection-ready examples with actions.
+- `agentRules`: source-example rules for AI agents.
+
+## Workflow
+
+1. Read `site-examples.json`.
+2. Choose the collection that matches the component or template.
+3. Copy the content shape, not just the words.
+4. Keep Utopia-specific language and routes.
+5. Do not create generic SaaS metrics, fake companies, decorative cards, or placeholder copy.

package/templates/agent-docs/index.md

@@ -0,0 +1,78 @@
+# Utopia Studio Design System for AI Agents
+
+Use this as the canonical design guidance when generating Utopia Studio UI.
+
+## Intent
+
+The interface is architectural, editorial, precise, calm, and commercially credible.
+
+## Rules
+
+- Utopia is the default/reference theme, not the whole design system.
+- For the Utopia brand site, use TWK Lausanne, Special Black, White, Brick Red, Light Grey, and black/red tints.
+- For themeable apps/templates, map every visual decision through semantic roles in `themes.json`.
+- Use `site-examples.json` for real Utopia examples before writing placeholder content.
+- Use `docs/design-system/examples.md` when a human-readable source-example summary is enough.
+- Use `templates.json` for page structure before inventing layouts.
+- Keep all primary surfaces square.
+- Use hairline borders instead of shadows.
+- In the Utopia theme, Brick Red is action, focus, active states, and emphasis.
+- Do not create gradients, glass panels, decorative blobs, or rounded SaaS cards.
+- Use semantic headings and visible focus states.
+
+## Theme Decision Gate
+
+Before generating UI, decide:
+
+1. Is this for the Utopia Studio brand site?
+2. Is this for a themeable app/template?
+3. Is this a new theme?
+
+Use the locked `utopia` theme for the brand site. For themeable contexts, use semantic roles and make sure every role in `themes.json` is defined before using a new theme.
+
+## Core Components
+
+Before inventing UI, inspect each component's `agentContract` in `packages/design-system/src/manifests/components.json`.
+Read component `props`, `anatomy`, `states`, and `slots` before composing examples.
+Before writing docs examples, inspect `packages/design-system/src/manifests/site-examples.json`.
+When reading quickly, use `docs/design-system/examples.md` for the generated source-example summary.
+Before scaffolding a page, inspect `packages/design-system/src/manifests/templates.json`.
+
+- Button
+- IconButton
+- ButtonGroup
+- Card
+- Badge
+- PageHero
+- CtaSection
+- Topbar
+
+## Agent Contract
+
+Each manifest component should define:
+
+- `useWhen`
+- `avoidWhen`
+- `fallbackToShadcn`
+- `requiredTokens`
+- `neverInvent`
+- `validationChecklist`
+
+Component entries can also define:
+
+- `props`
+- `anatomy`
+- `states`
+- `slots`
+
+If a needed UI primitive is missing, first try `npx shadcn@latest add <primitive> --yes`, then layer Utopia tokens and rules on top.
+
+## CLI
+
+```sh
+utopia-ds init
+utopia-ds add button
+utopia-ds add card
+utopia-ds tokens
+utopia-ds doctor
+```

package/templates/agent-docs/llms.txt

@@ -0,0 +1,33 @@
+# Utopia Studio Design System
+
+Canonical package: @utopia-studio-design/design-system
+CLI package: @utopia-studio-design/design-system-cli
+
+Read first:
+- docs/design-system/agent-docs/index.md
+- docs/design-system/examples.md
+- packages/design-system/src/tokens.json
+- packages/design-system/src/manifests/components.json
+- packages/design-system/src/manifests/patterns.json
+- packages/design-system/src/manifests/themes.json
+- packages/design-system/src/manifests/site-examples.json
+- packages/design-system/src/manifests/templates.json
+
+Agent contract:
+- Read each component's agentContract before creating UI.
+- Read component props, anatomy, states, and slots before composing examples.
+- Prefer fallbackToShadcn via `npx shadcn@latest add <primitive> --yes`.
+- Never invent tokens, colors, shapes, or component APIs outside the manifest.
+- Utopia is the default/reference theme, not the whole design system.
+- For the Utopia brand site use the locked Utopia theme; for themeable apps/templates map decisions through semantic roles.
+- Use site-examples.json for real Utopia sample copy before inventing examples.
+- Use docs/design-system/examples.md when a human-readable source-example summary is enough.
+- Use templates.json for page structure before inventing layouts.
+
+Design rules:
+- Square geometry.
+- TWK Lausanne only.
+- Utopia theme palette: Brick Red, Special Black, White, Light Grey, and approved tints.
+- Themeable architecture: use semantic roles before raw values.
+- Borders over shadows.
+- No gradients, glassmorphism, blobs, or rounded SaaS cards.

package/templates/components/badge.tsx

@@ -0,0 +1,12 @@
+import * as React from 'react'
+
+import { cn } from '../../lib/utils'
+
+export function Badge({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn('inline-flex w-fit items-center border px-2.5 py-1 text-xs font-medium uppercase', className)}
+      {...props}
+    />
+  )
+}

package/templates/components/brand-action.tsx

@@ -0,0 +1,32 @@
+import { cva, type VariantProps } from 'class-variance-authority'
+import type * as React from 'react'
+
+import { cn } from '../../lib/utils'
+
+const brandActionVariants = cva('brand-action', {
+  variants: {
+    variant: {
+      primary: 'brand-action--primary',
+      secondary: 'brand-action--secondary',
+      ghost: 'brand-action--ghost',
+    },
+  },
+  defaultVariants: {
+    variant: 'primary',
+  },
+})
+
+export interface BrandActionProps
+  extends React.AnchorHTMLAttributes<HTMLAnchorElement>,
+    VariantProps<typeof brandActionVariants> {
+  label: string
+}
+
+export function BrandAction({ className, label, variant, ...props }: BrandActionProps) {
+  return (
+    <a className={cn(brandActionVariants({ className, variant }))} {...props}>
+      <span>{label}</span>
+      {variant === 'primary' || !variant ? <span aria-hidden="true">-&gt;</span> : null}
+    </a>
+  )
+}

package/templates/components/button-group.tsx

@@ -0,0 +1,30 @@
+import * as React from 'react'
+
+import { cn } from '../../lib/utils'
+import { Button, type ButtonProps } from './button'
+
+export function ButtonGroup({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn('utopia-button-group', className)}
+      role="group"
+      {...props}
+    />
+  )
+}
+
+export const ButtonGroupButton = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant = 'secondary', ...props }, ref) => (
+    <Button
+      className={cn('utopia-button-group__button', className)}
+      ref={ref}
+      variant={variant}
+      {...props}
+    />
+  ),
+)
+
+ButtonGroupButton.displayName = 'ButtonGroupButton'

package/templates/components/button.tsx

@@ -0,0 +1,44 @@
+import * as React from 'react'
+import { Slot } from '@radix-ui/react-slot'
+import { cva, type VariantProps } from 'class-variance-authority'
+
+import { cn } from '../../lib/utils'
+
+const buttonVariants = cva(
+  'utopia-button inline-flex shrink-0 items-center justify-center disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        primary: '',
+        default: '',
+        destructive: 'bg-[hsl(var(--destructive))] text-[hsl(var(--destructive-foreground))]',
+        secondary: 'bg-[hsl(var(--secondary))] text-[hsl(var(--secondary-foreground))]',
+        outline: 'border-[hsl(var(--border))] bg-transparent text-[hsl(var(--foreground))]',
+        ghost: 'border-transparent bg-transparent text-[hsl(var(--foreground))]',
+        link: 'h-auto min-h-0 border-0 bg-transparent px-0 underline underline-offset-4 hover:text-[hsl(var(--primary))]',
+      },
+      size: {
+        default: '',
+        sm: 'h-[var(--button-height)] px-[var(--button-padding-x)]',
+        lg: 'h-12',
+        icon: 'size-11 p-0',
+      },
+    },
+    defaultVariants: { variant: 'primary', size: 'default' },
+  },
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+}
+
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ asChild = false, className, size, variant, ...props }, ref) => {
+    const Comp = asChild ? Slot : 'button'
+    return <Comp className={cn(buttonVariants({ className, size, variant }))} ref={ref} {...props} />
+  },
+)
+
+Button.displayName = 'Button'

package/templates/components/card.tsx

@@ -0,0 +1,23 @@
+import * as React from 'react'
+
+import { cn } from '../../lib/utils'
+
+export function Card({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn('utopia-card', className)} {...props} />
+}
+
+export function CardHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn('grid gap-1.5 p-5', className)} {...props} />
+}
+
+export function CardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  return <h3 className={cn('m-0 text-2xl font-medium leading-tight', className)} {...props} />
+}
+
+export function CardDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) {
+  return <p className={cn('m-0 text-sm leading-6 opacity-75', className)} {...props} />
+}
+
+export function CardContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn('p-5 pt-0', className)} {...props} />
+}

package/templates/components/cta-section.tsx

@@ -0,0 +1,34 @@
+import { cn } from '../../lib/utils'
+import { BrandAction } from './brand-action'
+
+type CtaAction = {
+  href: string
+  label: string
+  variant?: 'primary' | 'secondary' | 'ghost'
+}
+
+export function CtaSection({
+  actions,
+  className,
+  eyebrow,
+  title,
+}: {
+  actions: CtaAction[]
+  className?: string
+  eyebrow: string
+  title: string
+}) {
+  return (
+    <section className={cn('brand-cta-section', className)}>
+      <div className="brand-cta-section__inner">
+        <p className="brand-cta-section__eyebrow">{eyebrow}</p>
+        <h2 className="m-0 text-[length:var(--type-hero-title)] font-bold leading-none">{title}</h2>
+        <div className="brand-cta-section__actions">
+          {actions.map((action) => (
+            <BrandAction key={action.label} {...action} />
+          ))}
+        </div>
+      </div>
+    </section>
+  )
+}

package/templates/components/icon-button.tsx

@@ -0,0 +1,44 @@
+import * as React from 'react'
+
+import { cn } from '../../lib/utils'
+import { Button, type ButtonProps } from './button'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './tooltip'
+
+export interface IconButtonProps
+  extends Omit<ButtonProps, 'children' | 'size'> {
+  children: React.ReactNode
+  label: string
+  tooltip?: string
+}
+
+export const IconButton = React.forwardRef<HTMLButtonElement, IconButtonProps>(
+  ({ children, className, label, tooltip, variant = 'ghost', ...props }, ref) => {
+    const control = (
+      <Button
+        aria-label={label}
+        className={cn('utopia-icon-button', className)}
+        ref={ref}
+        size="icon"
+        variant={variant}
+        {...props}
+      >
+        {children}
+      </Button>
+    )
+
+    if (!tooltip) {
+      return control
+    }
+
+    return (
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger asChild>{control}</TooltipTrigger>
+          <TooltipContent>{tooltip}</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    )
+  },
+)
+
+IconButton.displayName = 'IconButton'

package/templates/components/page-hero.tsx

@@ -0,0 +1,47 @@
+import type { ReactNode } from 'react'
+
+import { cn } from '../../lib/utils'
+import { BrandAction } from './brand-action'
+
+type PageHeroAction = {
+  href: string
+  label: string
+  variant?: 'primary' | 'secondary' | 'ghost'
+}
+
+export function PageHero({
+  actions = [],
+  body,
+  className,
+  eyebrow,
+  panelClassName,
+  title,
+  variant = 'split',
+}: {
+  actions?: PageHeroAction[]
+  body?: ReactNode
+  className?: string
+  eyebrow: string
+  panelClassName?: string
+  title: string
+  variant?: 'split' | 'stacked'
+}) {
+  return (
+    <section className={cn('brand-page-hero', `brand-page-hero--${variant}`, className)}>
+      <div className="brand-page-hero__copy">
+        <p className="brand-page-hero__eyebrow">{eyebrow}</p>
+        <h1 className="m-0 text-[length:var(--type-hero-title)] font-bold leading-none tracking-0">{title}</h1>
+      </div>
+      <div className={cn('brand-page-hero__panel', panelClassName)}>
+        {body ? <p className="text-lg leading-7">{body}</p> : null}
+        {actions.length ? (
+          <div className="brand-page-hero__actions">
+            {actions.map((action) => (
+              <BrandAction key={action.label} {...action} />
+            ))}
+          </div>
+        ) : null}
+      </div>
+    </section>
+  )
+}

package/templates/components/tooltip.tsx

@@ -0,0 +1,48 @@
+import * as React from 'react'
+import { Tooltip as TooltipPrimitive } from 'radix-ui'
+
+import { cn } from '../../lib/utils'
+
+export function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      delayDuration={delayDuration}
+      {...props}
+    />
+  )
+}
+
+export function Tooltip({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return <TooltipPrimitive.Root {...props} />
+}
+
+export function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger {...props} />
+}
+
+export function TooltipContent({
+  children,
+  className,
+  sideOffset = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        className={cn('utopia-tooltip-content', className)}
+        sideOffset={sideOffset}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className="utopia-tooltip-arrow" />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  )
+}

package/templates/components/topbar.tsx

@@ -0,0 +1,59 @@
+import { Button } from './button'
+
+export type TopbarNavItem = {
+  href: string
+  label: string
+}
+
+export interface TopbarProps {
+  applyHref?: string
+  applyLabel?: string
+  brandHref?: string
+  brandLabel?: string
+  navItems?: TopbarNavItem[]
+  partnerHref?: string
+  partnerLabel?: string
+}
+
+const defaultNavItems: TopbarNavItem[] = [
+  { label: 'Fellows', href: '/fellows' },
+  { label: 'Startups', href: '/portfolio' },
+  { label: 'How We Build', href: '/how-we-build' },
+  { label: 'Team', href: '/team' },
+  { label: 'Resources', href: '/resources' },
+]
+
+export function Topbar({
+  applyHref,
+  applyLabel = 'Apply',
+  brandHref = '/',
+  brandLabel = 'The Utopia Studio',
+  navItems = defaultNavItems,
+  partnerHref,
+  partnerLabel = 'Partner with us',
+}: TopbarProps) {
+  return (
+    <header className="utopia-topbar">
+      <a className="utopia-topbar__brand" href={brandHref}>
+        {brandLabel}
+      </a>
+      <nav aria-label="Primary navigation" className="utopia-topbar__nav">
+        {navItems.map((item) => (
+          <a className="utopia-topbar__link" href={item.href} key={item.href}>
+            {item.label}
+          </a>
+        ))}
+        {partnerHref ? (
+          <Button asChild variant="outline">
+            <a href={partnerHref}>{partnerLabel}</a>
+          </Button>
+        ) : null}
+        {applyHref ? (
+          <Button asChild>
+            <a href={applyHref}>{applyLabel}</a>
+          </Button>
+        ) : null}
+      </nav>
+    </header>
+  )
+}

package/templates/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/templates/styles/styles.css

@@ -0,0 +1,271 @@
+@import './utopia-tokens.css';
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  background: hsl(var(--background));
+  color: hsl(var(--foreground));
+  font-family: var(--font-sans);
+  font-weight: var(--font-weight-regular);
+  font-synthesis: none;
+  text-rendering: geometricPrecision;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+button,
+a {
+  font: inherit;
+}
+
+.utopia-button {
+  align-items: center;
+  border-radius: 0;
+  display: inline-flex;
+  font-size: var(--button-font-size);
+  font-weight: var(--button-font-weight);
+  gap: var(--button-gap);
+  height: var(--button-height);
+  justify-content: center;
+  letter-spacing: var(--button-tracking);
+  padding-inline: var(--button-padding-x);
+  text-transform: uppercase;
+  transition: background 200ms ease, border-color 200ms ease, color 200ms ease;
+  white-space: nowrap;
+}
+
+.utopia-button:focus-visible,
+.brand-action:focus-visible {
+  outline: 2px solid hsl(var(--ring));
+  outline-offset: 2px;
+}
+
+.utopia-button--primary {
+  background: hsl(var(--primary));
+  border: 1px solid hsl(var(--primary));
+  color: hsl(var(--primary-foreground));
+}
+
+.utopia-button--primary:hover {
+  background: var(--brand-brick-hover);
+  border-color: var(--brand-brick-hover);
+}
+
+.utopia-button--destructive {
+  background: hsl(var(--destructive));
+  border: 1px solid hsl(var(--destructive));
+  color: hsl(var(--destructive-foreground));
+}
+
+.utopia-button--destructive:hover {
+  background: var(--brand-brick-hover);
+  border-color: var(--brand-brick-hover);
+}
+
+.utopia-button--secondary {
+  background: hsl(var(--secondary));
+  border: 1px solid hsl(var(--secondary));
+  color: hsl(var(--secondary-foreground));
+}
+
+.utopia-button--outline,
+.utopia-button--ghost {
+  background: transparent;
+  border: 1px solid hsl(var(--input));
+  color: hsl(var(--foreground));
+}
+
+.utopia-button--outline:hover,
+.utopia-button--ghost:hover {
+  border-color: hsl(var(--primary));
+  color: hsl(var(--primary));
+}
+
+.utopia-card {
+  background: hsl(var(--card));
+  border: 1px solid var(--tint-black-20);
+  border-radius: 0;
+  box-shadow: none;
+  color: hsl(var(--card-foreground));
+}
+
+.utopia-icon-button {
+  padding: 0;
+}
+
+.utopia-tooltip-content {
+  background: hsl(var(--foreground));
+  color: hsl(var(--background));
+  font-size: 12px;
+  line-height: 1;
+  padding: 8px 10px;
+  z-index: 50;
+}
+
+.utopia-tooltip-arrow {
+  fill: hsl(var(--foreground));
+}
+
+.utopia-button-group {
+  align-items: center;
+  display: inline-flex;
+}
+
+.utopia-button-group__button {
+  border-right-width: 0;
+}
+
+.utopia-button-group__button:last-child {
+  border-right-width: 1px;
+}
+
+.brand-action {
+  align-items: center;
+  border: 1px solid hsl(var(--input));
+  border-radius: 0;
+  display: inline-flex;
+  font-size: var(--button-font-size);
+  font-weight: var(--button-font-weight);
+  gap: var(--button-gap);
+  min-height: var(--button-height);
+  padding-inline: var(--button-padding-x);
+  text-transform: uppercase;
+  letter-spacing: var(--button-tracking);
+  transition: background 200ms ease, border-color 200ms ease, color 200ms ease;
+}
+
+.brand-action--primary {
+  background: hsl(var(--primary));
+  border-color: hsl(var(--primary));
+  color: hsl(var(--primary-foreground));
+}
+
+.brand-action--secondary,
+.brand-action--ghost {
+  background: transparent;
+  color: hsl(var(--foreground));
+}
+
+.brand-action--secondary:hover,
+.brand-action--ghost:hover {
+  border-color: hsl(var(--primary));
+  color: hsl(var(--primary));
+}
+
+.brand-page-hero {
+  display: grid;
+  gap: clamp(28px, 5vw, 72px);
+  grid-template-columns: minmax(0, 1.15fr) minmax(280px, 0.85fr);
+  padding: var(--section-padding-y) var(--section-padding-x);
+}
+
+.brand-page-hero--stacked {
+  grid-template-columns: 1fr;
+}
+
+.brand-page-hero__eyebrow,
+.brand-cta-section__eyebrow,
+.utopia-topbar__link {
+  font-size: var(--fs-eyebrow);
+  font-weight: var(--font-weight-medium);
+  letter-spacing: var(--tracking-eyebrow);
+  text-transform: uppercase;
+}
+
+.brand-page-hero h1,
+.brand-cta-section h2 {
+  font-family: var(--font-display);
+  font-size: var(--type-hero-title);
+  font-weight: var(--font-weight-strong);
+  letter-spacing: 0;
+  line-height: var(--lh-tight);
+  margin: 0;
+}
+
+.brand-page-hero__panel {
+  border-left: 1px solid hsl(var(--foreground) / 0.18);
+  padding-left: clamp(20px, 3vw, 40px);
+}
+
+.brand-page-hero__panel p {
+  font-size: var(--type-hero-description);
+  line-height: var(--lh-body);
+  margin: 0;
+}
+
+.brand-page-hero__actions,
+.brand-cta-section__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  margin-top: 28px;
+}
+
+.brand-cta-section {
+  padding: var(--section-padding-y) var(--section-padding-x);
+}
+
+.brand-cta-section__inner {
+  border-top: 1px solid hsl(var(--foreground) / 0.18);
+  padding-top: clamp(24px, 4vw, 44px);
+}
+
+.utopia-topbar {
+  align-items: center;
+  border-bottom: 1px solid hsl(var(--foreground) / 0.14);
+  display: flex;
+  gap: 24px;
+  min-height: var(--topbar-height);
+  padding-inline: var(--section-padding-x);
+}
+
+.utopia-topbar__brand {
+  font-size: 14px;
+  font-weight: var(--font-weight-strong);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.utopia-topbar__nav {
+  align-items: center;
+  display: flex;
+  gap: 18px;
+  margin-left: auto;
+}
+
+.utopia-topbar__link:hover {
+  color: hsl(var(--primary));
+}
+
+@media (max-width: 760px) {
+  .brand-page-hero {
+    grid-template-columns: 1fr;
+  }
+
+  .brand-page-hero__panel {
+    border-left: 0;
+    border-top: 1px solid hsl(var(--foreground) / 0.18);
+    padding-left: 0;
+    padding-top: 20px;
+  }
+
+  .utopia-topbar {
+    align-items: flex-start;
+    flex-direction: column;
+    padding-block: 18px;
+  }
+
+  .utopia-topbar__nav {
+    flex-wrap: wrap;
+    margin-left: 0;
+  }
+}

package/templates/styles/tokens.css

@@ -0,0 +1,21 @@
+:root {
+  --background: 342 9.1% 21.6%;
+  --foreground: 0 0% 100%;
+  --card: 0 0% 100%;
+  --card-foreground: 342 9.1% 21.6%;
+  --primary: 12 59.5% 50.6%;
+  --primary-foreground: 0 0% 100%;
+  --secondary: 0 0% 93.3%;
+  --secondary-foreground: 342 9.1% 21.6%;
+  --border: 0 0% 100% / 0.18;
+  --ring: 12 59.5% 50.6%;
+  --font-sans: 'TWK Lausanne';
+  --font-weight-regular: 350;
+  --font-weight-medium: 500;
+  --font-weight-strong: 700;
+  --radius: 0px;
+  --type-hero-title: clamp(54px, 6.1vw, 112px);
+  --button-height: 44px;
+  --button-font-size: 14px;
+  --button-tracking: 0.06em;
+}

package/templates/tokens.json

@@ -0,0 +1,41 @@
+{
+  "name": "Utopia Studio Design System",
+  "version": "0.1.0",
+  "defaultTheme": "utopia",
+  "themeArchitecture": "Utopia is the default/reference theme. Components must consume semantic roles so other themes can be added without changing component APIs.",
+  "semanticRoles": [
+    "--background",
+    "--foreground",
+    "--card",
+    "--card-foreground",
+    "--primary",
+    "--primary-foreground",
+    "--secondary",
+    "--secondary-foreground",
+    "--muted",
+    "--muted-foreground",
+    "--border",
+    "--input",
+    "--ring",
+    "--radius"
+  ],
+  "color": {
+    "specialBlack": "hsl(342 9.1% 21.6%)",
+    "white": "hsl(0 0% 100%)",
+    "brickRed": "hsl(12 59.5% 50.6%)",
+    "brickHover": "hsl(12 61.4% 44.7%)",
+    "brickPress": "hsl(12 62.1% 38.2%)",
+    "lightGrey": "hsl(0 0% 93.3%)"
+  },
+  "radius": {
+    "base": "0px",
+    "max": "0px",
+    "button": "0px"
+  },
+  "font": {
+    "family": "TWK Lausanne",
+    "regular": 350,
+    "medium": 500,
+    "strong": 700
+  }
+}