@zvoove/unity-ui 2.21.0 → 2.22.0

package/bin/generate-skills.mjs

@@ -220,6 +220,98 @@ const SHADCN_MAP = {
   useClickOutside: null,
 };
 
+// ─── MUI equivalence map ─────────────────────────────────────────────────────
+const MUI_BASE = 'https://mui.com/material-ui/react-';
+const MUI_X_BASE = 'https://mui.com/x/react-';
+
+const MUI_MAP = {
+  Accordion: { name: 'Accordion', url: `${MUI_BASE}accordion/` },
+  ActionCard: null,
+  Avatar: { name: 'Avatar', url: `${MUI_BASE}avatar/` },
+  Badge: { name: 'Badge', url: `${MUI_BASE}badge/` },
+  Breadcrumbs: { name: 'Breadcrumbs', url: `${MUI_BASE}breadcrumbs/` },
+  Button: { name: 'Button', url: `${MUI_BASE}button/` },
+  Card: { name: 'Card', url: `${MUI_BASE}card/` },
+  ChatBubble: null,
+  Checkbox: { name: 'Checkbox', url: `${MUI_BASE}checkbox/` },
+  Chip: { name: 'Chip', url: `${MUI_BASE}chip/` },
+  CodeBlock: null,
+  ConfirmationCard: {
+    name: 'Dialog',
+    url: `${MUI_BASE}dialog/`,
+    note: 'Use a Dialog with confirmation actions. ConfirmationCard is an inline card, not a modal.',
+  },
+  ContentBlock: null,
+  DatePicker: {
+    name: 'DatePicker',
+    url: `${MUI_X_BASE}date-picker/`,
+    note: 'MUI X component — requires @mui/x-date-pickers.',
+  },
+  Dialog: { name: 'Dialog', url: `${MUI_BASE}dialog/` },
+  Divider: { name: 'Divider', url: `${MUI_BASE}divider/` },
+  Expandable: { name: 'Collapse', url: `${MUI_BASE}collapse/` },
+  FormLabel: { name: 'FormLabel', url: `${MUI_BASE}text-field/` },
+  Grid: { name: 'Grid', url: `${MUI_BASE}grid/` },
+  Icon: { name: 'SvgIcon', url: `${MUI_BASE}icons/` },
+  InfoBox: { name: 'Alert', url: `${MUI_BASE}alert/` },
+  MessageActions: null,
+  Pagination: { name: 'Pagination', url: `${MUI_BASE}pagination/` },
+  PopUpMenu: { name: 'Menu', url: `${MUI_BASE}menu/` },
+  ProgressIndicator: {
+    name: 'LinearProgress / CircularProgress',
+    url: `${MUI_BASE}progress/`,
+  },
+  Radio: { name: 'RadioGroup', url: `${MUI_BASE}radio-button/` },
+  ScoreCard: null,
+  Segment: {
+    name: 'ToggleButtonGroup',
+    url: `${MUI_BASE}toggle-button/`,
+  },
+  Select: { name: 'Select', url: `${MUI_BASE}select/` },
+  Sheet: {
+    name: 'Drawer',
+    url: `${MUI_BASE}drawer/`,
+    note: 'Use a temporary or persistent Drawer.',
+  },
+  SideNavigation: {
+    name: 'Drawer (persistent)',
+    url: `${MUI_BASE}drawer/`,
+  },
+  Skeleton: { name: 'Skeleton', url: `${MUI_BASE}skeleton/` },
+  Snackbar: { name: 'Snackbar', url: `${MUI_BASE}snackbar/` },
+  Stack: { name: 'Stack', url: `${MUI_BASE}stack/` },
+  Switch: { name: 'Switch', url: `${MUI_BASE}switch/` },
+  Table: {
+    name: 'Table / DataGrid',
+    url: `${MUI_BASE}table/`,
+    note: 'For advanced features use MUI X DataGrid (@mui/x-data-grid).',
+  },
+  Tabs: { name: 'Tabs', url: `${MUI_BASE}tabs/` },
+  Tag: {
+    name: 'Chip',
+    url: `${MUI_BASE}chip/`,
+    note: 'MUI Chip covers static labels; Unity UI Tag is display-only with more color/tone variants.',
+  },
+  TextField: { name: 'TextField', url: `${MUI_BASE}text-field/` },
+  Textarea: {
+    name: 'TextField (multiline)',
+    url: `${MUI_BASE}text-field/`,
+    note: 'Use TextField with multiline and rows props.',
+  },
+  Tooltip: { name: 'Tooltip', url: `${MUI_BASE}tooltip/` },
+  TopBar: { name: 'AppBar', url: `${MUI_BASE}app-bar/` },
+  Typography: { name: 'Typography', url: `${MUI_BASE}typography/` },
+  Uploader: null,
+  useBreakpoint: {
+    name: 'useMediaQuery',
+    url: 'https://mui.com/material-ui/react-use-media-query/',
+  },
+  useClickOutside: {
+    name: 'ClickAwayListener',
+    url: `${MUI_BASE}click-away-listener/`,
+  },
+};
+
 // ─── Storybook documentation links ───────────────────────────────────────────
 // Maps component name → Storybook title path (as defined in *.stories.tsx).
 // URL: https://main--67c03f013fea08bb2f926e5f.chromatic.com/?path=/docs/<path>--docs
@@ -358,6 +450,8 @@ function detectSection(line) {
     '## RULES FOR AI AGENTS': 'rules',
     '## SPACING SCALE': 'spacing',
     '## ICON NAMES': 'icons',
+    '## STYLING': 'styling',
+    '## CUSTOM COMPONENT': 'customComponent',
   };
 
   for (const [prefix, key] of Object.entries(sectionHeaders)) {
@@ -394,6 +488,8 @@ function parseLlmsTxt(content) {
     responsive: [],
     rules: [],
     spacing: [],
+    styling: [],
+    customComponent: [],
     icons: [],
     example: [],
   };
@@ -415,6 +511,11 @@ function parseLlmsTxt(content) {
   }
 
   function handleComponentHeader(line) {
+    // In prose sections, ### sub-headings are content, not component names
+    if (activeSection === 'styling' || activeSection === 'customComponent') {
+      handleContentLine(line);
+      return;
+    }
     flush();
     currentComponent = line.slice(4).trim();
     if (activeSection !== 'icons') activeSection = null;
@@ -445,6 +546,8 @@ function parseLlmsTxt(content) {
     responsive: trimBucket('responsive'),
     rules: trimBucket('rules'),
     spacing: trimBucket('spacing'),
+    styling: trimBucket('styling'),
+    customComponent: trimBucket('customComponent'),
     icons: trimBucket('icons'),
     example: trimBucket('example'),
     components,
@@ -471,6 +574,7 @@ function generateComponentSkill(name, content) {
   if (shadcn) {
     description += ` Comparable to shadcn/ui ${shadcn.name}.`;
   }
+  description += String.raw`\nTRIGGER when: user needs ${name} in a project using @zvoove/unity-ui.\nDO NOT read dist/ or source files — all API docs are in this skill.`;
 
   const frontmatter = [
     '---',
@@ -577,14 +681,21 @@ function generateIndexSkill(componentNames) {
         `| ${n} | [${SHADCN_MAP[n].name}](${SHADCN_MAP[n].url}) | \`unity-ui-${kebabCase(n)}\` |`
     );
 
+  const muiRows = componentNames
+    .filter((n) => MUI_MAP[n])
+    .map(
+      (n) =>
+        `| ${n} | [${MUI_MAP[n].name}](${MUI_MAP[n].url}) | \`unity-ui-${kebabCase(n)}\` |`
+    );
+
   const uniqueRows = componentNames
-    .filter((n) => !SHADCN_MAP[n])
-    .map((n) => `| ${n} | — | \`unity-ui-${kebabCase(n)}\` |`);
+    .filter((n) => !SHADCN_MAP[n] && !MUI_MAP[n])
+    .map((n) => `| ${n} | \`unity-ui-${kebabCase(n)}\` |`);
 
   const frontmatter = [
     '---',
     'name: unity-ui-index',
-    'description: "Component index for Unity UI (@zvoove/unity-ui). Maps all 40+ components to their shadcn/ui equivalents. Use this to find the right component."',
+    'description: "Component index for Unity UI (@zvoove/unity-ui). Maps all 40+ components to their shadcn/ui and MUI equivalents. Use this to find the right component or migrate from another library."',
     'category: index',
     '---',
   ].join('\n');
@@ -595,17 +706,23 @@ function generateIndexSkill(componentNames) {
 
 > Use this index to find the right Unity UI component. Each component has its own skill with full documentation.
 
-## Components with shadcn/ui Equivalents
+## shadcn/ui → Unity UI
 
 | Unity UI | shadcn/ui | Skill |
 |----------|-----------|-------|
 ${shadcnRows.join('\n')}
 
+## MUI → Unity UI
+
+| Unity UI | MUI | Skill |
+|----------|-----|-------|
+${muiRows.join('\n')}
+
 ## Unity UI–Only Components
 
-| Unity UI | shadcn/ui | Skill |
-|----------|-----------|-------|
-${uniqueRows.join('\n')}
+| Unity UI | Skill |
+|----------|-------|
+${uniqueRows.map((r) => r.replace(' | — ', '')).join('\n')}
 
 ## How to Use Skills
 
@@ -615,6 +732,1074 @@ AI agents should load the relevant skill when they need to use a specific compon
   );
 }
 
+function generateStylingSkill(parsed) {
+  const description = [
+    'Styling guide for Unity UI (@zvoove/unity-ui). Tailwind CSS v4 + design tokens + tailwind-variants.',
+    'TRIGGER when: user needs to style a custom element, asks about CSS/styling, or produces inline styles / arbitrary Tailwind values in a @zvoove/unity-ui project.',
+    'DO NOT use inline styles, arbitrary Tailwind values, or raw CSS — use design tokens and tv() instead.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-styling',
+    `description: "${description}"`,
+    'category: styling',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter + `\n\n# Unity UI — Styling Guide\n\n` + parsed.styling + '\n'
+  );
+}
+
+function generateCustomComponentSkill(parsed) {
+  const description = [
+    'Guide for creating a custom component in a project using @zvoove/unity-ui, following the same conventions as the design system.',
+    'TRIGGER when: user needs to create a custom component that does not exist in @zvoove/unity-ui, following Unity UI patterns.',
+    'DO NOT TRIGGER when: an existing Unity UI component already covers the use case — use that instead.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-custom-component',
+    `description: "${description}"`,
+    'category: authoring',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Creating a Custom Component\n\n` +
+    parsed.customComponent +
+    '\n'
+  );
+}
+
+function generateFormsSkill() {
+  const description = [
+    'Form composition guide for @zvoove/unity-ui with react-hook-form and zod.',
+    'TRIGGER when: user is building a form, adding validation, wiring inputs to a form library, or asking how to use Unity UI inputs with react-hook-form.',
+    'DO NOT use register() — Unity UI inputs are controlled components; always use Controller.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-forms',
+    `description: "${description}"`,
+    'category: forms',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Form Composition
+
+> Unity UI inputs are **controlled components**. Use \`Controller\` from react-hook-form — never \`register()\`.
+
+## Installing
+
+\`\`\`bash
+npm install react-hook-form zod @hookform/resolvers
+\`\`\`
+
+## Basic Pattern
+
+\`\`\`tsx
+import { useForm, Controller } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Button, Select, Stack, TextField } from '@zvoove/unity-ui';
+
+const schema = z.object({
+  email: z.string().email('Ungültige E-Mail-Adresse'),
+  role: z.string().min(1, 'Pflichtfeld'),
+});
+
+type FormValues = z.infer<typeof schema>;
+
+export function ExampleForm() {
+  const { control, handleSubmit } = useForm<FormValues>({
+    resolver: zodResolver(schema),
+    defaultValues: { email: '', role: '' },
+  });
+
+  return (
+    <form onSubmit={handleSubmit((data) => console.log(data))}>
+      <Stack direction="column" gap="md">
+        <Controller
+          name="email"
+          control={control}
+          render={({ field, fieldState }) => (
+            <TextField
+              {...field}
+              label="E-Mail"
+              error={!!fieldState.error}
+              errorMessage={fieldState.error?.message}
+            />
+          )}
+        />
+        <Controller
+          name="role"
+          control={control}
+          render={({ field, fieldState }) => (
+            <Select
+              {...field}
+              label="Rolle"
+              options={[
+                { value: 'admin', label: 'Administrator' },
+                { value: 'user', label: 'Benutzer' },
+              ]}
+              error={!!fieldState.error}
+              errorMessage={fieldState.error?.message}
+            />
+          )}
+        />
+        <Stack direction="row" gap="sm" justify="flex-end">
+          <Button type="submit" variant="filled">Speichern</Button>
+        </Stack>
+      </Stack>
+    </form>
+  );
+}
+\`\`\`
+
+## Input Binding Reference
+
+| Component | Binding pattern | Notes |
+|-----------|----------------|-------|
+| TextField | \`{...field}\` | value + onChange + onBlur + name |
+| Textarea | \`{...field}\` | same as TextField |
+| Select | \`{...field}\` | value + onChange |
+| Checkbox | \`checked={field.value}\` | use \`checked\`, not \`value\` |
+| Switch | \`checked={field.value}\` | use \`checked\`, not \`value\` |
+| DatePicker | \`value={field.value} onChange={field.onChange}\` | pass date value directly |
+| Radio (RadioGroup) | \`value={field.value} onChange={field.onChange}\` | — |
+
+## Checkbox / Switch Pattern
+
+\`\`\`tsx
+<Controller
+  name="acceptTerms"
+  control={control}
+  render={({ field }) => (
+    <Checkbox
+      label="Ich akzeptiere die Nutzungsbedingungen"
+      checked={field.value ?? false}
+      onChange={(e) => field.onChange(e.target.checked)}
+    />
+  )}
+/>
+\`\`\`
+
+## DatePicker Pattern
+
+\`\`\`tsx
+<Controller
+  name="birthDate"
+  control={control}
+  render={({ field, fieldState }) => (
+    <DatePicker
+      label="Geburtsdatum"
+      value={field.value}
+      onChange={field.onChange}
+      error={!!fieldState.error}
+      errorMessage={fieldState.error?.message}
+    />
+  )}
+/>
+\`\`\`
+
+## Complete Login Form
+
+\`\`\`tsx
+import { useForm, Controller } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Button, Card, Checkbox, Stack, TextField, Typography } from '@zvoove/unity-ui';
+
+const loginSchema = z.object({
+  email: z.string().email('Ungültige E-Mail-Adresse'),
+  password: z.string().min(8, 'Mindestens 8 Zeichen erforderlich'),
+  rememberMe: z.boolean().optional(),
+});
+
+type LoginValues = z.infer<typeof loginSchema>;
+
+export function LoginForm() {
+  const {
+    control,
+    handleSubmit,
+    formState: { isSubmitting },
+  } = useForm<LoginValues>({
+    resolver: zodResolver(loginSchema),
+    defaultValues: { email: '', password: '', rememberMe: false },
+  });
+
+  const onSubmit = async (data: LoginValues) => {
+    await login(data);
+  };
+
+  return (
+    <Card padding="xl">
+      <form onSubmit={handleSubmit(onSubmit)}>
+        <Stack direction="column" gap="md">
+          <Typography variant="title-large">Anmelden</Typography>
+
+          <Controller
+            name="email"
+            control={control}
+            render={({ field, fieldState }) => (
+              <TextField
+                {...field}
+                label="E-Mail"
+                type="email"
+                error={!!fieldState.error}
+                errorMessage={fieldState.error?.message}
+              />
+            )}
+          />
+
+          <Controller
+            name="password"
+            control={control}
+            render={({ field, fieldState }) => (
+              <TextField
+                {...field}
+                label="Passwort"
+                type="password"
+                error={!!fieldState.error}
+                errorMessage={fieldState.error?.message}
+              />
+            )}
+          />
+
+          <Controller
+            name="rememberMe"
+            control={control}
+            render={({ field }) => (
+              <Checkbox
+                label="Angemeldet bleiben"
+                checked={field.value ?? false}
+                onChange={(e) => field.onChange(e.target.checked)}
+              />
+            )}
+          />
+
+          <Stack direction="row" justify="flex-end">
+            <Button type="submit" variant="filled" disabled={isSubmitting}>
+              {isSubmitting ? 'Wird angemeldet…' : 'Anmelden'}
+            </Button>
+          </Stack>
+        </Stack>
+      </form>
+    </Card>
+  );
+}
+\`\`\`
+
+## Rules
+
+- NEVER use \`register()\` — Unity UI inputs are controlled components; always use \`Controller\`
+- ALWAYS use \`zodResolver\` from \`@hookform/resolvers/zod\` for schema validation
+- Checkbox and Switch require \`checked={field.value}\` — not \`value\`
+- Display errors with \`error={!!fieldState.error}\` + \`errorMessage={fieldState.error?.message}\`
+- Use \`Stack\` for form layout — never raw \`<div>\` with flexbox CSS
+- Default texts, labels, and validation messages must be in German
+`
+  );
+}
+
+function generateLayoutsSkill() {
+  const description = [
+    'Common app layout patterns for @zvoove/unity-ui: app shells, dashboards, settings pages, master/detail.',
+    'TRIGGER when: user is building a page layout, app shell, or multi-section UI in a @zvoove/unity-ui project.',
+    'DO NOT use raw div + CSS for layout — always use Stack, Grid, TopBar, SideNavigation.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-layouts',
+    `description: "${description}"`,
+    'category: layout',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Layout Patterns
+
+> Use \`Stack\` and \`Grid\` for all layout. Never use raw \`<div style={{ display: 'flex' }}>\`.
+
+## App Shell (TopBar + SideNavigation)
+
+\`\`\`tsx
+import { Avatar, SideNavigation, Stack, TopBar } from '@zvoove/unity-ui';
+
+export function AppShell({ children }: { children: React.ReactNode }) {
+  const [activeId, setActiveId] = useState('dashboard');
+
+  return (
+    <Stack direction="column" style={{ height: '100vh' }}>
+      <TopBar
+        title="Meine App"
+        actions={<Avatar initials="AB" />}
+      />
+      <Stack direction="row" style={{ flex: 1, overflow: 'hidden' }}>
+        <SideNavigation
+          items={[
+            { id: 'dashboard', label: 'Dashboard', icon: 'House' },
+            { id: 'users', label: 'Benutzer', icon: 'Users' },
+            { id: 'settings', label: 'Einstellungen', icon: 'Gear' },
+          ]}
+          activeId={activeId}
+          onSelect={setActiveId}
+        />
+        <Stack
+          direction="column"
+          padding="xl"
+          style={{ flex: 1, overflow: 'auto' }}
+        >
+          {children}
+        </Stack>
+      </Stack>
+    </Stack>
+  );
+}
+\`\`\`
+
+## Dashboard Layout
+
+\`\`\`tsx
+<Stack direction="column" gap="lg" padding="xl">
+  <Typography variant="headline-small">Dashboard</Typography>
+
+  {/* KPI summary row */}
+  <Grid columns={{ mobile: 1, tablet: 2, desktop: 4 }} gap="md">
+    {kpis.map((kpi) => (
+      <Card key={kpi.id} padding="md">
+        <Stack direction="column" gap="xs">
+          <Typography variant="label-medium">{kpi.label}</Typography>
+          <Typography variant="display-small">{kpi.value}</Typography>
+        </Stack>
+      </Card>
+    ))}
+  </Grid>
+
+  {/* Main area: 2/3 table + 1/3 sidebar */}
+  <Grid columns={{ mobile: 1, laptop: 3 }} gap="lg">
+    <Stack style={{ gridColumn: 'span 2' }}>
+      <Card padding="md">
+        <Table columns={columns} rows={rows} />
+      </Card>
+    </Stack>
+    <Stack direction="column" gap="md">
+      <Card padding="md">
+        <Typography variant="title-medium">Aktivität</Typography>
+        {/* activity list */}
+      </Card>
+    </Stack>
+  </Grid>
+</Stack>
+\`\`\`
+
+## Settings Page (Two-Column)
+
+\`\`\`tsx
+<Stack direction="column" gap="xl" padding="xl">
+  <Typography variant="headline-small">Einstellungen</Typography>
+
+  <Stack direction={{ mobile: 'column', tablet: 'row' }} gap="xl">
+    {/* Left: section label */}
+    <Stack direction="column" gap="xs" style={{ minWidth: 200 }}>
+      <Typography variant="title-medium">Profil</Typography>
+      <Typography variant="body-medium">Persönliche Informationen.</Typography>
+    </Stack>
+
+    {/* Right: fields */}
+    <Card padding="lg" style={{ flex: 1 }}>
+      <Stack direction="column" gap="md">
+        <Stack direction={{ mobile: 'column', tablet: 'row' }} gap="md">
+          <TextField label="Vorname" value={firstName} onChange={setFirstName} />
+          <TextField label="Nachname" value={lastName} onChange={setLastName} />
+        </Stack>
+        <TextField label="E-Mail" value={email} onChange={setEmail} />
+        <Switch
+          label="E-Mail-Benachrichtigungen aktivieren"
+          checked={notifications}
+          onChange={(e) => setNotifications(e.target.checked)}
+        />
+      </Stack>
+    </Card>
+  </Stack>
+
+  {/* Sticky action bar */}
+  <Stack direction="row" gap="sm" justify="flex-end">
+    <Button variant="outlined">Abbrechen</Button>
+    <Button variant="filled">Speichern</Button>
+  </Stack>
+</Stack>
+\`\`\`
+
+## Master / Detail (List + Detail)
+
+\`\`\`tsx
+<Stack
+  direction={{ mobile: 'column', tablet: 'row' }}
+  gap="md"
+  padding="xl"
+  style={{ height: '100%' }}
+>
+  {/* List panel */}
+  <Stack direction="column" gap="sm" style={{ width: 300, flexShrink: 0 }}>
+    {items.map((item) => (
+      <Card
+        key={item.id}
+        padding="md"
+        onClick={() => setSelected(item.id)}
+      >
+        <Typography variant="body-medium">{item.title}</Typography>
+      </Card>
+    ))}
+  </Stack>
+
+  {/* Detail panel */}
+  <Stack direction="column" gap="md" style={{ flex: 1 }}>
+    {selected ? (
+      <Card padding="lg">{/* detail content */}</Card>
+    ) : (
+      <Stack direction="column" align="center" justify="center" style={{ height: '100%' }}>
+        <Typography variant="body-medium">Wählen Sie einen Eintrag aus.</Typography>
+      </Stack>
+    )}
+  </Stack>
+</Stack>
+\`\`\`
+
+## Centered Auth / Empty State
+
+\`\`\`tsx
+<Stack
+  direction="column"
+  align="center"
+  justify="center"
+  style={{ minHeight: '100vh' }}
+  gap="lg"
+>
+  <Card padding="xl" style={{ width: '100%', maxWidth: 400 }}>
+    <Stack direction="column" gap="md">
+      <Typography variant="headline-small">Anmelden</Typography>
+      {/* form fields */}
+    </Stack>
+  </Card>
+</Stack>
+\`\`\`
+
+## Card Grid (Content Listing)
+
+\`\`\`tsx
+<Stack direction="column" gap="lg" padding="xl">
+  <Stack direction="row" justify="space-between" align="center">
+    <Typography variant="headline-small">Projekte</Typography>
+    <Button variant="filled" icon="Plus">Neues Projekt</Button>
+  </Stack>
+
+  <Grid columns={{ mobile: 1, tablet: 2, desktop: 3 }} gap="md">
+    {projects.map((project) => (
+      <Card key={project.id} padding="md">
+        <Stack direction="column" gap="sm">
+          <Typography variant="title-medium">{project.name}</Typography>
+          <Typography variant="body-small">{project.description}</Typography>
+          <Stack direction="row" gap="xs" justify="flex-end">
+            <Button variant="ghost" size="sm">Bearbeiten</Button>
+          </Stack>
+        </Stack>
+      </Card>
+    ))}
+  </Grid>
+</Stack>
+\`\`\`
+
+## Rules
+
+- Use \`Stack\` and \`Grid\` for ALL layout — never \`<div style={{ display: 'flex' }}>\`
+- Use \`TopBar\` + \`SideNavigation\` for app shells — never custom nav bars
+- Use \`Card\` for content containers — never styled divs
+- Use spacing tokens for gap/padding — never arbitrary pixel values (\`gap-lg\` not \`gap-5\`)
+- Always make layouts responsive with \`ResponsiveType\` props
+- SideNavigation handles its own responsive collapse — do not wrap it in conditional rendering
+`
+  );
+}
+
+function generateDarkModeSkill() {
+  const description = [
+    'Dark mode setup and theme toggling for @zvoove/unity-ui projects.',
+    'TRIGGER when: user wants to add dark mode, a theme toggle, or asks how Unity UI dark mode works.',
+    'DO NOT use prefers-color-scheme media queries or className=\\"dark\\" — Unity UI uses data-theme=\\"dark\\".',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-dark-mode',
+    `description: "${description}"`,
+    'category: theming',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Dark Mode
+
+> Dark mode is activated by \`data-theme="dark"\` on any ancestor element.
+> All semantic design tokens adapt automatically — no per-component changes needed.
+
+## How It Works
+
+\`\`\`html
+<!-- Light mode (default) -->
+<div>...</div>
+
+<!-- Dark mode — applies to this element and all descendants -->
+<div data-theme="dark">...</div>
+\`\`\`
+
+Unity UI uses Tailwind's **selector strategy** (\`[data-theme="dark"]\`), not the class or media-query strategy.
+Configure Tailwind accordingly if you need \`dark:\` in custom components:
+
+\`\`\`ts
+// tailwind.config.ts
+export default {
+  darkMode: ['selector', '[data-theme="dark"]'],
+};
+\`\`\`
+
+## React ThemeProvider
+
+\`\`\`tsx
+import { createContext, useContext, useEffect, useState } from 'react';
+
+type Theme = 'light' | 'dark';
+
+const ThemeContext = createContext<{
+  theme: Theme;
+  toggleTheme: () => void;
+}>({ theme: 'light', toggleTheme: () => {} });
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setTheme] = useState<Theme>(() => {
+    const stored = localStorage.getItem('theme') as Theme | null;
+    if (stored) return stored;
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  });
+
+  // Sync with OS preference changes (only when no stored preference)
+  useEffect(() => {
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const handler = (e: MediaQueryListEvent) => {
+      if (!localStorage.getItem('theme')) {
+        setTheme(e.matches ? 'dark' : 'light');
+      }
+    };
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, []);
+
+  const toggleTheme = () => {
+    setTheme((t) => {
+      const next = t === 'light' ? 'dark' : 'light';
+      localStorage.setItem('theme', next);
+      return next;
+    });
+  };
+
+  return (
+    <ThemeContext.Provider value={{ theme, toggleTheme }}>
+      <div data-theme={theme} style={{ minHeight: '100vh' }}>
+        {children}
+      </div>
+    </ThemeContext.Provider>
+  );
+}
+
+export const useTheme = () => useContext(ThemeContext);
+\`\`\`
+
+Wrap the app root:
+
+\`\`\`tsx
+// main.tsx
+<ThemeProvider>
+  <App />
+</ThemeProvider>
+\`\`\`
+
+## Theme Toggle Button
+
+\`\`\`tsx
+import { Button } from '@zvoove/unity-ui';
+import { useTheme } from './ThemeProvider';
+
+export function ThemeToggle() {
+  const { theme, toggleTheme } = useTheme();
+
+  return (
+    <Button
+      variant="ghost"
+      icon={theme === 'dark' ? 'Sun' : 'Moon'}
+      onClick={toggleTheme}
+      aria-label={
+        theme === 'dark'
+          ? 'Zum hellen Modus wechseln'
+          : 'Zum dunklen Modus wechseln'
+      }
+    />
+  );
+}
+\`\`\`
+
+Place it in \`TopBar\`'s \`actions\` prop:
+
+\`\`\`tsx
+<TopBar title="Meine App" actions={<ThemeToggle />} />
+\`\`\`
+
+## Token Behaviour in Dark Mode
+
+Semantic tokens adapt automatically — no \`dark:\` prefix needed for these:
+
+| Token | Light | Dark |
+|-------|-------|------|
+| \`bg-surface\` | white / light gray | dark gray |
+| \`bg-primary\` | brand color | lighter brand color |
+| \`text-on-surface\` | near-black | near-white |
+| \`text-on-surface-variant\` | gray | lighter gray |
+| \`border-outline\` | gray border | darker border |
+| \`bg-background\` | page background | dark page background |
+
+Only use \`dark:\` for values **outside** the token system (custom hex colors, images, etc.).
+
+## Storybook Dark Mode
+
+\`\`\`tsx
+// In a story file
+export const DarkMode: Story = {
+  decorators: [
+    (Story) => (
+      <div data-theme="dark" style={{ padding: '1rem', background: 'var(--color-background)' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+\`\`\`
+
+Or use the Storybook backgrounds addon — set the decorator on the global level in \`preview.ts\`.
+
+## Rules
+
+- NEVER use \`prefers-color-scheme\` CSS to apply dark mode — use \`data-theme="dark"\`
+- NEVER use \`className="dark"\` — Unity UI uses the selector strategy, not the class strategy
+- Semantic tokens adapt automatically — only add \`dark:\` for custom non-token values
+- Persist theme in \`localStorage\` to avoid a flash-of-wrong-theme on reload
+- Do not apply \`data-theme\` to \`<html>\` or \`<body>\` unless your React root is there
+`
+  );
+}
+
+function generateMigrateShadcnSkill(componentNames) {
+  const description = [
+    'Step-by-step guide for migrating a shadcn/ui codebase to @zvoove/unity-ui.',
+    'TRIGGER when: user wants to migrate from shadcn/ui to Unity UI, or is converting shadcn/ui components.',
+    'DO NOT keep shadcn/ui imports alongside Unity UI — replace fully.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-migrate-shadcn',
+    `description: "${description}"`,
+    'category: migration',
+    '---',
+  ].join('\n');
+
+  const componentRows = componentNames
+    .filter((n) => SHADCN_MAP[n])
+    .map((n) => {
+      const s = SHADCN_MAP[n];
+      const note = s.note ? ` _(${s.note})_` : '';
+      return `| [${s.name}](${s.url}) | \`<${n} />\` | \`unity-ui-${kebabCase(n)}\`${note} |`;
+    });
+
+  const noEquivalent = componentNames
+    .filter((n) => !SHADCN_MAP[n])
+    .map(
+      (n) => `- **${n}** — load skill \`unity-ui-${kebabCase(n)}\` for usage`
+    )
+    .join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Migrating from shadcn/ui to Unity UI
+
+## Step-by-Step Process
+
+1. **Install Unity UI** — see \`unity-ui-setup\` skill
+2. **Run a global find** for \`from "@/components/ui/\` and \`from "~/components/ui/\` — those are shadcn/ui imports
+3. **Replace each component** using the table below — load the \`unity-ui-<component>\` skill for full props
+4. **Replace styling** — remove Tailwind class-heavy JSX and use Unity UI props instead
+5. **Remove shadcn/ui** — delete the \`components/ui/\` folder and uninstall \`class-variance-authority\`, \`cmdk\`, \`@radix-ui\` etc.
+
+## Component Map
+
+| shadcn/ui | Unity UI | Skill |
+|-----------|----------|-------|
+${componentRows.join('\n')}
+
+## Unity UI–Only Components (no shadcn/ui equivalent)
+
+${noEquivalent}
+
+## Common Prop Differences
+
+| Pattern | shadcn/ui | Unity UI |
+|---------|-----------|----------|
+| Text input | \`<Input />\` | \`<TextField label="..." />\` |
+| Validation error | custom error \`<p>\` | \`error={true} errorMessage="..."\` |
+| Button icon | wrap with \`<Icon />\` | \`icon="IconName"\` prop |
+| Loading state | manual spinner | \`loading={true}\` prop (Button) |
+| Form field wrapper | \`<FormField>\` + \`<FormControl>\` | direct Controller render |
+| Toast | \`toast("msg")\` from sonner | \`addSnackbar("msg")\` from useSnackbar |
+| Sheet position | \`side="right"\` | \`anchor="right"\` |
+
+## Removing shadcn/ui
+
+\`\`\`bash
+# Remove shadcn/ui dependencies
+npm uninstall @radix-ui/react-* class-variance-authority cmdk lucide-react
+
+# Delete the generated component folder
+rm -rf src/components/ui
+\`\`\`
+
+## Rules
+
+- NEVER keep shadcn/ui and Unity UI components side-by-side — migrate fully
+- Replace all \`cn()\` usage in component files with \`twMerge()\` from tailwind-merge
+- shadcn/ui uses \`className\` extensively — Unity UI uses props (variant, size, etc.); remove the class overrides
+- Import everything from \`@zvoove/unity-ui\`, never from local \`components/ui/\`
+`
+  );
+}
+
+function generateMigrateMuiSkill(componentNames) {
+  const description = [
+    'Step-by-step guide for migrating a Material UI (MUI) codebase to @zvoove/unity-ui.',
+    'TRIGGER when: user wants to migrate from MUI (@mui/material) to Unity UI, or is converting MUI components.',
+    'DO NOT keep MUI imports alongside Unity UI — replace fully.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-migrate-mui',
+    `description: "${description}"`,
+    'category: migration',
+    '---',
+  ].join('\n');
+
+  const componentRows = componentNames
+    .filter((n) => MUI_MAP[n])
+    .map((n) => {
+      const m = MUI_MAP[n];
+      const note = m.note ? ` _(${m.note})_` : '';
+      return `| [${m.name}](${m.url}) | \`<${n} />\` | \`unity-ui-${kebabCase(n)}\`${note} |`;
+    });
+
+  const noEquivalent = componentNames
+    .filter((n) => !MUI_MAP[n])
+    .map(
+      (n) => `- **${n}** — load skill \`unity-ui-${kebabCase(n)}\` for usage`
+    )
+    .join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Migrating from MUI to Unity UI
+
+## Step-by-Step Process
+
+1. **Install Unity UI** — see \`unity-ui-setup\` skill
+2. **Run a global find** for \`from "@mui/material\` and \`from "@mui/x-\` — those are MUI imports
+3. **Replace each component** using the table below — load the \`unity-ui-<component>\` skill for full props
+4. **Replace the sx prop** — MUI's \`sx\` system does not exist in Unity UI; use Tailwind tokens instead (load \`unity-ui-styling\`)
+5. **Remove ThemeProvider** — Unity UI uses \`data-theme="dark"\` for dark mode; load \`unity-ui-dark-mode\`
+6. **Uninstall MUI** after all components are replaced
+
+## Component Map
+
+| MUI | Unity UI | Skill |
+|-----|----------|-------|
+${componentRows.join('\n')}
+
+## Unity UI–Only Components (no MUI equivalent)
+
+${noEquivalent}
+
+## Common Pattern Differences
+
+| Pattern | MUI | Unity UI |
+|---------|-----|----------|
+| Theming | \`<ThemeProvider theme={theme}>\` | \`data-theme="dark"\` attribute |
+| Dark mode | \`createTheme({ palette: { mode: 'dark' } })\` | \`data-theme="dark"\` on container |
+| Inline styles | \`sx={{ mt: 2, color: 'primary.main' }}\` | Tailwind tokens: \`className="mt-md text-primary"\` |
+| Custom style prop | \`sx={{ ... }}\` | \`className\` with token classes |
+| Text field | \`<TextField variant="outlined" label="..." />\` | \`<TextField label="..." />\` |
+| Grid v2 | \`<Grid container spacing={2}>\` | \`<Grid columns={3} gap="md">\` |
+| Stack spacing | \`<Stack spacing={2}>\` | \`<Stack gap="md">\` |
+| Icons | \`import EditIcon from '@mui/icons-material/Edit'\` | \`<Icon name="Pencil" />\` |
+| Button loading | \`<LoadingButton loading>\` | \`<Button loading>\` |
+| Alert | \`<Alert severity="error">\` | \`<InfoBox variant="error">\` |
+| Snackbar | \`<Snackbar>...</Snackbar>\` (imperative) | \`addSnackbar()\` from \`useSnackbar()\` |
+
+## Replacing the sx Prop
+
+MUI's \`sx\` prop maps CSS properties to theme values. Replace with Tailwind design tokens:
+
+\`\`\`tsx
+// MUI
+<Box sx={{ mt: 2, mb: 3, color: 'text.secondary', bgcolor: 'background.paper' }}>
+
+// Unity UI
+<Stack direction="column" gap="md" className="text-on-surface-variant bg-surface">
+\`\`\`
+
+See the \`unity-ui-styling\` skill for the full token reference.
+
+## Removing MUI
+
+\`\`\`bash
+npm uninstall @mui/material @mui/x-date-pickers @mui/icons-material @emotion/react @emotion/styled
+\`\`\`
+
+## Rules
+
+- NEVER keep MUI and Unity UI components side-by-side — migrate fully
+- The \`sx\` prop does not exist in Unity UI — use \`className\` with token classes or component props
+- MUI icons do not exist in Unity UI — use \`<Icon name="..." />\` (load \`unity-ui-icons\` skill for names)
+- Remove \`ThemeProvider\` and \`CssBaseline\` from MUI; Unity UI uses CSS custom properties from \`theme.css\`
+- Import everything from \`@zvoove/unity-ui\`
+`
+  );
+}
+
+function generateFigmaCodeConnectSkill() {
+  const description = [
+    'Figma Code Connect setup for @zvoove/unity-ui — links Figma components to Unity UI React components.',
+    'TRIGGER when: user wants to set up Figma Code Connect, link design components to code, or improve design-to-code accuracy in a Unity UI project.',
+    'DO NOT use this for general Figma-to-code generation — Code Connect is for mapping design components to existing code components.',
+  ].join(String.raw`\n`);
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui-figma-code-connect',
+    `description: "${description}"`,
+    'category: tooling',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Figma Code Connect
+
+> Code Connect links Figma components to Unity UI React components so that when a designer shares a Figma URL, the AI knows exactly which component and props to use.
+
+## Install
+
+\`\`\`bash
+npm install --save-dev @figma/code-connect
+\`\`\`
+
+## Configuration
+
+Create \`figma.config.json\` at the project root:
+
+\`\`\`json
+{
+  "codeConnect": {
+    "parser": "react",
+    "include": ["src/**/*.figma.tsx"],
+    "importPaths": {
+      "@zvoove/unity-ui": "@zvoove/unity-ui"
+    }
+  }
+}
+\`\`\`
+
+## How to Get the Figma Node ID
+
+1. Open the Unity UI Figma design file
+2. Select the component you want to connect
+3. Copy the URL — it contains \`node-id=<nodeId>\`
+4. Convert \`-\` to \`:\` in the node ID (e.g. \`123-456\` → \`123:456\`)
+
+## Mapping File Structure
+
+Create a \`.figma.tsx\` file next to each component (or in a \`figma/\` folder):
+
+\`\`\`tsx
+// src/figma/Button.figma.tsx
+import figma from '@figma/code-connect';
+import { Button } from '@zvoove/unity-ui';
+
+figma.connect(
+  Button,
+  'https://www.figma.com/design/<FILE_KEY>/<FILE_NAME>?node-id=<NODE_ID>',
+  {
+    props: {
+      variant: figma.enum('Variant', {
+        filled: 'filled',
+        outlined: 'outlined',
+        ghost: 'ghost',
+        text: 'text',
+      }),
+      size: figma.enum('Size', {
+        sm: 'sm',
+        md: 'md',
+        lg: 'lg',
+      }),
+      disabled: figma.boolean('Disabled'),
+      label: figma.string('Label'),
+    },
+    example: ({ variant, size, disabled, label }) => (
+      <Button variant={variant} size={size} disabled={disabled}>
+        {label}
+      </Button>
+    ),
+  }
+);
+\`\`\`
+
+## Example: TextField
+
+\`\`\`tsx
+// src/figma/TextField.figma.tsx
+import figma from '@figma/code-connect';
+import { TextField } from '@zvoove/unity-ui';
+
+figma.connect(
+  TextField,
+  'https://www.figma.com/design/<FILE_KEY>/<FILE_NAME>?node-id=<NODE_ID>',
+  {
+    props: {
+      label: figma.string('Label'),
+      placeholder: figma.string('Placeholder'),
+      error: figma.boolean('Error'),
+      disabled: figma.boolean('Disabled'),
+    },
+    example: ({ label, placeholder, error, disabled }) => (
+      <TextField
+        label={label}
+        placeholder={placeholder}
+        error={error}
+        disabled={disabled}
+      />
+    ),
+  }
+);
+\`\`\`
+
+## Publish to Figma
+
+\`\`\`bash
+# Preview what will be published (dry run)
+npx figma connect publish --dry-run --token <FIGMA_ACCESS_TOKEN>
+
+# Publish
+npx figma connect publish --token <FIGMA_ACCESS_TOKEN>
+\`\`\`
+
+Store the token in \`.env.local\` (never commit it):
+
+\`\`\`bash
+FIGMA_ACCESS_TOKEN=figd_xxxxxxxx
+\`\`\`
+
+\`\`\`bash
+npx figma connect publish --token $FIGMA_ACCESS_TOKEN
+\`\`\`
+
+## Figma Prop Types Reference
+
+| Figma layer type | Code Connect helper | Example |
+|-----------------|---------------------|---------|
+| Variant property | \`figma.enum()\` | \`figma.enum('Variant', { filled: 'filled' })\` |
+| Boolean property | \`figma.boolean()\` | \`figma.boolean('Disabled')\` |
+| Text layer | \`figma.string()\` | \`figma.string('Label')\` |
+| Instance swap | \`figma.instance()\` | \`figma.instance('Icon')\` |
+| Nested instance | \`figma.nestedProps()\` | \`figma.nestedProps('Slot', { ... })\` |
+
+## Rules
+
+- Create one \`.figma.tsx\` file per component
+- The Figma URL must point to the **main component** (not an instance or frame)
+- Prop names in \`figma.enum()\` must match Figma's exact property names (case-sensitive)
+- Never commit Figma access tokens — use environment variables
+- After updating, republish with \`npx figma connect publish\`
+`
+  );
+}
+
+function generateUmbrellaSkill(componentNames) {
+  const description = [
+    'Unity UI (@zvoove/unity-ui) component library router. Use this as the entry point when building UI with this package.',
+    'TRIGGER when: user wants to build UI, use a component, or migrate/convert a UI from any source (Lovable, Figma Make, shadcn/ui, MUI, Ant Design, etc.) into this design system.',
+    'DO NOT TRIGGER when: @zvoove/unity-ui is not installed in the project.',
+  ].join(String.raw`\n`);
+
+  const componentList = componentNames
+    .map((n) => `- ${n} → load skill \`unity-ui-${kebabCase(n)}\``)
+    .join('\n');
+
+  const frontmatter = [
+    '---',
+    'name: unity-ui',
+    `description: "${description}"`,
+    'category: routing',
+    '---',
+  ].join('\n');
+
+  return (
+    frontmatter +
+    `\n\n# Unity UI — Component Router
+
+> **@zvoove/unity-ui** is installed in this project. Use the skills below — do NOT read \`dist/\`, \`node_modules/\`, or source files for API documentation.
+
+## How to Use
+
+1. Find the component you need in the directory below
+2. Load its \`unity-ui-<component>\` skill for full props, examples, and rules
+3. Import exclusively from \`@zvoove/unity-ui\` — never from dist paths
+
+## Component Directory
+
+${componentList}
+
+## Rules
+
+- NEVER read \`dist/\` or \`node_modules/@zvoove/unity-ui/\` for type/API information — skills have everything
+- NEVER create custom components for functionality already provided by this library
+- Always import from \`@zvoove/unity-ui\`
+- If unsure which component to use, load \`unity-ui-index\` for the full shadcn/ui equivalence table
+
+## Migrating from Other Libraries
+
+If the project contains components from shadcn/ui, MUI, Ant Design, Lovable, Figma Make, or any other source:
+- **Replace them with Unity UI equivalents** — do not keep mixed component libraries
+- Load \`unity-ui-index\` to find the equivalent Unity UI component
+- Remove the replaced library's imports and dependencies once converted
+- Prefer Unity UI over any other component library, regardless of what already exists in the codebase
+`
+  );
+}
+
 // ─── Write skills to disk ───────────────────────────────────────────────────
 
 function writeSkill(outputDir, slug, content) {
@@ -664,18 +1849,66 @@ function main() {
   }
 
   // Meta skills
+  writeSkill(outputDir, 'unity-ui', generateUmbrellaSkill(componentNames));
   writeSkill(outputDir, 'unity-ui-setup', generateSetupSkill(parsed));
+  writeSkill(outputDir, 'unity-ui-styling', generateStylingSkill(parsed));
+  writeSkill(
+    outputDir,
+    'unity-ui-custom-component',
+    generateCustomComponentSkill(parsed)
+  );
   writeSkill(outputDir, 'unity-ui-icons', generateIconsSkill(parsed));
   writeSkill(outputDir, 'unity-ui-index', generateIndexSkill(componentNames));
-  count += 3;
+  writeSkill(outputDir, 'unity-ui-forms', generateFormsSkill());
+  writeSkill(outputDir, 'unity-ui-layouts', generateLayoutsSkill());
+  writeSkill(outputDir, 'unity-ui-dark-mode', generateDarkModeSkill());
+  writeSkill(
+    outputDir,
+    'unity-ui-migrate-shadcn',
+    generateMigrateShadcnSkill(componentNames)
+  );
+  writeSkill(
+    outputDir,
+    'unity-ui-migrate-mui',
+    generateMigrateMuiSkill(componentNames)
+  );
+  writeSkill(
+    outputDir,
+    'unity-ui-figma-code-connect',
+    generateFigmaCodeConnectSkill()
+  );
+  count += 12;
 
   const relOutput = path.relative(projectRoot, outputDir);
   console.log(`\n  Unity UI — Agent Skills Generator\n`);
   console.log(`  ✅ Generated ${count} skills in ${relOutput}/\n`);
   console.log(`     ${componentNames.length} component skills`);
+  console.log(`     1 umbrella routing skill (entry point + migration rules)`);
   console.log(`     1 setup skill (installation, spacing, responsive props)`);
+  console.log(
+    `     1 styling skill (Tailwind v4 tokens, tv(), no inline styles)`
+  );
+  console.log(
+    `     1 custom component skill (patterns for creating new components)`
+  );
   console.log(`     1 icons skill (all icon names)`);
-  console.log(`     1 index skill (shadcn/ui mapping table)\n`);
+  console.log(`     1 index skill (shadcn/ui + MUI mapping tables)`);
+  console.log(
+    `     1 forms skill (react-hook-form + zod + Controller pattern)`
+  );
+  console.log(
+    `     1 layouts skill (app shells, dashboards, settings, master/detail)`
+  );
+  console.log(
+    `     1 dark mode skill (data-theme, ThemeProvider, token behaviour)`
+  );
+  console.log(
+    `     1 migrate-shadcn skill (step-by-step shadcn/ui → Unity UI)`
+  );
+  console.log(`     1 migrate-mui skill (step-by-step MUI → Unity UI)`);
+  console.log(
+    `     1 figma-code-connect skill (Code Connect setup and mappings)\n`
+  );
   console.log(`  Your AI agent can now discover and use Unity UI components.`);
   console.log(`  Skills are loaded on-demand — only relevant ones are read.\n`);
 }