شروع سریع

npx -y pnpm@10.18.0 create next-app@latest tokapps-shop \  --typescript --app --eslint --no-src-dir --import-alias "@/*" --use-pnpmcd tokapps-shop

{ "type": "module", "packageManager": "pnpm@10.18.0" }

{  "dependencies": {    "@tokapps/tuk": "^0.2.2",    "@tokapps/tokens": "^0.2.2",    "@tokapps/primitives": "^0.2.2",    "@tokapps/icons": "^0.2.2",    "@tokapps/next": "^0.2.2",    "@tokapps/theme-tokapps": "^0.2.2",    "@tokapps/patterns": "^0.2.2",    "next": "^16.4.0",    "react": "^19.0.1",    "react-dom": "^19.0.1"  },  "devDependencies": {    "typescript": "^7.0.2",    "@types/node": "^22.14.0",    "@types/react": "^19.3.0",    "@types/react-dom": "^19.3.0"  }}

{  "dependencies": {    "@tokapps/motion": "^0.2.2",    "@tokapps/gestures": "^0.2.2",    "@tokapps/sound": "^0.2.2",    "@tokapps/accessibility": "^0.2.2"  }}

npx -y pnpm@10.18.0 install

// next.config.tsimport { withTokapps } from '@tokapps/next/config';export default withTokapps({  reactStrictMode: true,  transpilePackages: ['@tokapps/next', '@tokapps/theme-tokapps'],});

// types/modules.d.tsdeclare module '*.css';declare module '@tokapps/tokens/css';declare module 'qrcode';

/* app/globals.css */html {  background: var(--tds-bg-canvas);  color: var(--tds-fg-default);  font-family: var(--tds-font-family-fa);  line-height: var(--tds-line-height-normal);}html[dir='ltr'] {  font-family: var(--tds-font-family-latin);  line-height: var(--tds-line-height-latin);}body { margin: 0; min-height: 100dvh; }

// theme/identity.tsexport const identity = {  brand: { name: 'فروشگاه نمونه', logo: '/logo.svg' },  dock: {    menu: [      { slug: 'home', label: 'خانه', href: '/' },      { slug: 'shop:products', label: 'محصولات', href: '/products', name: 'shop:products' },      { slug: 'dashboard', label: 'داشبورد', href: '/dashboard' },    ],    search: { method: 'command-menu', endpoint: '/search?q={query}', minChars: 2 },    mode: 'system',    sound: false,    clock: { calendar: 'jalali', face: 'digital' },    groupable: ['shop:*'],    // توجه: ProductDock هنوز identity.dock.responsive را مصرف نمی‌کند؛ فعلاً فقط اعلامی است.    responsive: {      layout: 'auto',      align: 'center',      size: 'md',      labels: true,      grouping: 'folder',      expandable: true,      maxVisible: 6,      expandableBelow: 4,      mobileBehavior: 'sheet',    },  },  channels: {    print: 'show', // فقط 'show' | 'hide'    readAloud: 'on',    sound: 'subtle',    gestures: ['tap'],    drag: 'off',  },  alerts: {    position: 'dock',    success: 'notify',    error: 'notify',    destructive: 'confirm',  },  login: { arrival: 'prism' },} as const;/** کانال‌های آماده که روی Button/Card ریخته می‌شوند ({...buttonChannels}) */export const buttonChannels = { print: identity.channels.print, onSound: identity.channels.sound } as const;

// theme/meta.tsimport type { ProductThemeMeta } from '@tokapps/tokens';export const meta: ProductThemeMeta = {  id: 'shop',  name: 'Shop Template',  nameFa: 'قالب فروشگاه',  description: 'مسی گرم با نمایش ورود منشوری',  product: 'فروشگاه نمونه',  hue: 35, chroma: 0.12, radiusScale: 1.15, headingWeight: 700,  density: 1, motion: 'soft', illustration: 'editorial', icons: null,  arrival: 'prism',  codeScheme: 'dark',  dockClock: { calendar: 'jalali', face: 'digital' },  dock: {    slots: { menu: true, search: true, mode: true, sound: true, profile: true, clock: true },    groupable: ['shop:*'],  },  layout: 'campaign',};

/* theme/theme.css */[data-theme='tokapps'] {  --tds-accent-hue: 35;  --tds-accent-chroma: 0.12;  --tds-radius-scale: 1.15;  --tds-font-weight-heading: 700;  --tds-arrival-style: prism;  --tds-arrival-intro: 1.1s;  --tds-arrival-flight: 0.9s;  --tds-arrival-land: 0.6s;}

// theme/index.tsimport '@tokapps/theme-tokapps';   // هویت پایهimport './theme.css';import { registerArrival } from '@tokapps/tuk/dock';import { prism } from './arrival';export { meta } from './meta';registerArrival('prism', prism);

// app/layout.tsximport type { Metadata, Viewport } from 'next';import type { ReactNode } from 'react';import { TokappsFonts, TokappsProvider, tokappsHtmlProps } from '@tokapps/next';import { TopBar } from '@tokapps/tuk/topbar';import { ProductDock } from '@tokapps/tuk/dock';import '@tokapps/tokens/css';import './globals.css';import { meta } from '../theme';import { identity } from '../theme/identity';export const metadata: Metadata = { title: { default: identity.brand.name, template: '%s · ' + identity.brand.name } };export const viewport: Viewport = { width: 'device-width', initialScale: 1 };export default function RootLayout({ children }: { children: ReactNode }) {  return (    <html {...tokappsHtmlProps}>      <head><TokappsFonts basePath="/fonts/vazir" /></head>      <body>        <TokappsProvider>          <TopBar label={identity.brand.name}>            <img src={identity.brand.logo} alt="" width={28} height={28} />          </TopBar>          <main data-dock-reserve>{children}</main>          <ProductDock            policy={meta.dock}            clockDefault={meta.dockClock}            signInHref="/login"            sections={identity.dock.menu.map((s) => ({              slug: s.slug,              label: s.label,              href: s.href,              icon: null,            }))}          />        </TokappsProvider>      </body>    </html>  );}

'use client';// components/DockSearch.tsx — روت layout سرور است؛ داکت و پاپ‌آپ را اینجا می‌سازیمconst [q, setQ] = useState('');const [open, setOpen] = useState(false);<ProductDock onSearch={() => setOpen(true)} … /><CommandMenu  open={open}  onOpenChange={setOpen}  hotkey="mod+k"                                    // با کیبورد هم باز می‌شود  placeholder={identity.dock.search.placeholder}  filter={false}                                    // نتایج از endpoint می‌آید  onQueryChange={(v) => { setQ(v); if (v.length >= identity.dock.search.minChars) search(v); }}  items={results}  onSelect={(item) => router.push(item.href)}/>

import Link from 'next/link';import { Breadcrumb } from '@tokapps/tuk';export function IdeaCrumbs() {  return (    <Breadcrumb      items={[        { id: 'home', label: 'خانه', href: '/' },        { id: 'shop', label: 'فروشگاه', href: '/products' },        { id: 'product', label: 'محصول ویژه' },      ]}      renderLink={({ children, ...props }) => <Link {...props}>{children}</Link>}    />  );}

// components/SoundBridge.tsx'use client';import { useEffect } from 'react';import { setSoundEmitter } from '@tokapps/tuk/sound';import { SoundProvider, useSound } from '@tokapps/sound';function Emitter() {  const play = useSound();  useEffect(() => {    setSoundEmitter(play);    return () => setSoundEmitter(null);  }, [play]);  return null;}export function SoundBridge({ children }: { children: React.ReactNode }) {  return (    <SoundProvider sound="subtle">      <Emitter />      {children}    </SoundProvider>  );}

import { Button } from '@tokapps/tuk';import { buttonChannels } from '../theme/identity'; // کانال‌های آماده از identity<Button {...buttonChannels} onClick={submit}>ارسال</Button>

'use client';import { useState } from 'react';import { useSwipe, resolveGesturePolicy } from '@tokapps/gestures';export function SwipeRow({ label }: { label: string }) {  const [gone, setGone] = useState(false);  // معادل دسترس‌پذیر (alternative) اجباری است؛ بدون آن هوک خطا می‌دهد  const { bind, getFallbackProps } = useSwipe({    direction: 'inline-start',    onSwipe: () => setGone(true),    // معادل دسترس‌پذیر اجباری است: { label، perform }    alternative: { label: 'بایگانی', perform: () => setGone(true) },  });  return (    <li {...bind}>      {label}      <button {...getFallbackProps()}>بایگانی</button>    </li>  );}// سیاست ژست هر کامپوننت را از schema می‌گیریم؛ مقدار نامعتبر به پیش‌فرض برمی‌گرددconst { policy, diagnostics } = resolveGesturePolicy({  component: 'list-item',  allowed: ['tap', 'swipe'],  options: { swipeDistancePx: 48 },});

import { printProps, readAloudProps, checkReadAloud } from '@tokapps/accessibility';<div {...printProps({ display: 'hide' })}>دکمه‌های تعاملی در چاپ پنهان می‌شوند</div><img {...readAloudProps({ decorative: true })} src="/ornament.svg" alt="" />// در dev: checkReadAloud(document.querySelector('main')!) → آرایهٔ ایرادها

// data/events.tsimport type { CalendarItem } from '@tokapps/tuk';export const events: CalendarItem[] = [  // رویداد سه‌روزه و تمام‌روز  { id: 'conf', title: 'کنفرانس سالانه', start: new Date(2026, 10, 3), end: new Date(2026, 10, 5), allDay: true, kind: 'event', tone: 'success' },  // رویداد ساعت‌دار  { id: 'demo', title: 'دموی محصول', start: new Date(2026, 10, 4, 15, 30), end: new Date(2026, 10, 4, 16, 15), kind: 'event', description: 'اتاق ۲' },  // تسک با چک‌باکس انجام  { id: 't1', title: 'ارسال پیش‌نویس', start: new Date(2026, 10, 4, 9, 30), kind: 'task', done: false, tone: 'brand' },];

import { Calendar } from '@tokapps/tuk';import { events } from '../data/events';<Calendar aria-label="رویدادهای من" items={events} onItemToggle={(item, done) => persist(item.id, done)} />

<ProductDock … calendarItems={events} />

// theme/arrival.tsimport type { Arrival } from '@tokapps/tuk/dock';import './arrival.css';export const prism: Arrival = async (ctx) => {  ctx.part('veil');                                   // پردهٔ مشترک، زیر داک  const stage = ctx.part('stage');  // اطلاعات واقعی کاربر: تصویر پروفایل، نام و نام خانوادگی، و meta (لوکیشن/نقش/…)  const avatar = ctx.user.avatarUrl    ? ctx.image('avatar', ctx.user.avatarUrl, stage)    : ctx.part('avatar', ctx.initials, stage);  ctx.part('name', ctx.user.name, stage);  const meta = [ctx.user.meta?.location, ctx.user.meta?.role].filter(Boolean).join(' · ');  if (meta) ctx.part('meta', meta, stage);  const shock = ctx.part('shock');  ctx.phase('intro');  await ctx.wait(ctx.ms('--tds-arrival-intro'));  ctx.phase('flight');  ctx.dockState('receiving');  const c = ctx.targetCenter();  if (c) Object.assign(shock.style, { left: `${c.x}px`, top: `${c.y}px` });  await ctx.flyTo(avatar);                            // تصویر پروفایل روی آیکون حساب داک  ctx.land();                                         // آواتار واقعی در داک  ctx.phase('land');  ctx.dockState('landed');  await ctx.wait(ctx.ms('--tds-arrival-land'));};

/* theme/arrival.css — فقط توکن زمان و منحنی؛ بدون رنگ خام */[data-tds='arrival'][data-style='prism'] [data-part='avatar'] {  animation: tds-prism-in calc(var(--tds-arrival-intro) * 0.5) var(--tds-ease-spring) both;}[data-tds='arrival'][data-style='prism']:not([data-phase='intro']) [data-part='name'] {  animation: tds-arrival-fade-out calc(var(--tds-arrival-flight) * 0.3) var(--tds-ease-out) both;}@keyframes tds-prism-in { from { opacity: 0; transform: scale(0.4); } to { opacity: 1; transform: none; } }

import { AuthFlow } from '@tokapps/patterns';import { signInSuccess } from '@tokapps/tuk/dock';// هر دادهٔ کاربر که نمایش باید نشان دهد؛ avatarUrl روی آیکون حساب داک می‌نشیندawait signInSuccess({ name, email, avatarUrl, meta: { location, role } });router.replace('/dashboard');           // ناوبری کلاینت تا نشست داک حفظ شود

import { Podcast, type PodcastEpisode } from '@tokapps/patterns';import { playOnDock, dockPlayer, useDockPlayer } from '@tokapps/tuk/dock';const episodes: PodcastEpisode[] = [  { id: 'ep-2', number: 2, title: 'هویت متغیر، بنیان ثابت', date: '۱۳ مهر ۱۴۰۵', duration: 2280, src: '/audio/ep-2.mp3' },];// فهرست اپیزودها: پخش هر اپیزود، کل فهرست را از همان‌جا روی داک می‌گذارد<Podcast show={{ title: 'پادکست ما', author: 'تیم ما' }} episodes={episodes} />// پخش از هر جای دیگر برنامه (فقط با کنش کاربر):<Button onClick={() => playOnDock(episodes.map(episodeToTrack), { start: 0, label: 'پادکست ما' })}>پخش</Button>dockPlayer.setView('minimized');                  // نماها: mini (پیش‌فرض)، minimized (دیسک)، expanded (برگهٔ داک)const player = useDockPlayer(dockPlayer);          // { queue, index, status, position, view, … }

npx -y pnpm@10.18.0 exec tsc --noEmit      # بدون خطاnpx -y pnpm@10.18.0 exec next dev          # پیش‌نمایش در مرورگر

{  "mcpServers": {    "tds": {      "command": "npx",      "args": ["-y", "pnpm@10.18.0", "--dir", "packages/tdm-mcp", "exec", "tsx", "src/server.ts"]    }  }}

<!-- پرامپت شروع پروژهٔ جدید با TDS — منبع: https://tds.tokapps.com/get-started -->تو یک مهندس فرانت‌اند هستی که با «دیزاین سیستم توکاپس» (TDS) کار می‌کند. این پرامپت کامل است؛ همه‌چیز را از همین متن بخوان و طبق آن عمل کن.> **توقف — اگر پروژه از قبل وجود دارد:** اگر پوشهٔ پروژه از قبل کد دارد (یا پروژه‌ای در کار است)، این پرامپت را رها کن و از پرامپت مهاجرت پروژهٔ موجود استفاده کن (‏/prompts/existing-project.md). این پرامپت برای ساختن پروژهٔ تازه است و نباید پروژهٔ خام کنار پروژهٔ فعلی بسازد.## اطلاعات پروژه- نوع کار: [پروژهٔ صفر / مهاجرت پروژهٔ موجود به TDS]- نام محصول: <نام محصول>        (اگر ندادی: «اپ نمونه»)- پوشهٔ پروژه: <مسیر>- صفحه‌های اصلی: <مثلاً لندینگ، ورود، داشبورد>- اگر مهاجرت است: مسیر پروژهٔ فعلی، فریم‌ورک فعلی (مثلاً CRA/Vue/قدیمی)، و رنگ‌های فعلی را بنویس.## ۰. قواعد اجباری — قبل از هر کاری0. سرور MCP آنلاین این پروژه: {{MCP_URL}} (با توکن شخصی برنامه‌نویس، هدر `Authorization: Bearer <توکن>`). اگر در دسترس است، اول قواعد اجباری پروژه را از آن بگیر (ابزار get_project_rules یا get_agent_bundle)، پرسونا، فونت‌ها و لوگو را عیناً رعایت کن و بستهٔ قواعد را در مخزن پروژه ذخیره کن.1. اگر سرور MCP با نام «tds» در دسترس است، اول get_mandatory_rules را صدا بزن و قواعد را عیناً رعایت کن. اگر نیست، با این دستور اجرایش کن:   npx -y pnpm@10.18.0 --dir packages/tdm-mcp exec tsx src/server.ts   (برای پروژهٔ بیرونی TDS_ROOT را به ریشهٔ checkout مونوریپو TDS بده.)2. داکت شیشه‌ای شناور پایین ناوبری اصلی است و هر شش کلید ثابت را دارد (منو، جستجو، حالت، صدا، پروفایل، ساعت). همیشه ProductDock از @tokapps/tuk/dock؛ هرگز Dock خام.3. بالای صفحه فقط داکت لوگوی برند است (TopBar با لوگو و نام برند). هیچ منو، جستجو یا <header> ناوبری بالای صفحه نمی‌آید.4. جریان ورود پس از موفقیت باید signInSuccess(user) از @tokapps/tuk/dock را اجرا کند (که نمایش ورود تم را پخش می‌کند) و بعد با ناوبری کلاینت برود. انتقال مستقیم ممنوع.5. نمایش ورود باید اطلاعات واقعی کاربر را با انیمیشن نشان دهد (نام و نام خانوادگی، تصویر پروفایلِ user.avatarUrl، و هر دادهٔ لازم دیگر مثل لوکیشن/نقش در user.meta) و با ctx.flyTo همان تصویر پروفایل را روی آیکون حساب کاربری داک بنشاند؛ بعد داک کاربر را لاگین‌شده نشان می‌دهد. تصمیم درباره اینکه چه نشان داده شود و کل صفحه چطور انیمیت شود با خود پروژه است، ولی نمایش بدون flyTo ناقص است.6. کلید جستجوی داکت باید یک پاپ‌آپ زنده باز کند: در identity.dock.search هر سهٔ method (command-menu یا page)، endpoint (مثل /search?q={query}) و minChars را تعیین کن و کلید جستجو را با onSearch روی ProductDock به CommandMenu وصل کن. کلید مرده و نوار جستجوی درون‌خطی ممنوع.7. صفحه‌ها فضای داک را با data-dock-reserve رزرو کنند.8. صدا، پادکست و موسیقی فقط با پخش‌کنندهٔ داک: فهرست اپیزودها را با الگوی Podcast از @tokapps/patterns بساز و هر پخش دیگری را با playOnDock/dockPlayer از @tokapps/tuk/dock به داک بفرست. پخش‌کنندهٔ محلی نساز: <audio>، new Audio()، HTMLAudioElement، کتابخانهٔ پخش‌کننده (react-player/howler/plyr/…‌) و کوچک‌کنندهٔ اختصاصی ممنوع. سه نما (کوچک، کوچک‌شده/دیسک، بزرگ)، صف پخش، دریافت/اشتراک و ادامهٔ پخش با تغییر صفحه از خود پخش‌کننده می‌آید و بازسازی‌شدنی نیست.9. فقط توکن معنایی --tds-*؛ رنگ خام، هگز و گرادیان آزاد ممنوع. فقط شش کلید ثابت داک طبق سیاست تم؛ موقعیتشان ثابت است.10. هیچ کامپوننت مشترک TDS را تغییر نده. برای هویت تازه فقط تم/قالب پروژه بساز.11. در صفحه‌ها اول کامپوننت‌های دیزاین‌کیت را به‌کار ببر (Button، Input، Table، Heading، Card و …). اگر کامپوننت/الگو/توکنی در کیت موجود نیست، عنصر خام نساز؛ به من اطلاع بده تا در پروژهٔ دیزاین‌کیت تعریف شود.12. پیش از تحویل، validate_agent_output باید خالی از خطا باشد — از جمله سه کد پرتکرار: layout/dock-search (پاپ‌آپ جستجو)، layout/media-player-kit (پخش‌کنندهٔ محلی به‌جای پخش‌کنندهٔ داک) و auth/arrival-target (پرواز تصویر پروفایل به آیکون حساب).## ۱. هویت پروژه — اولین قدم، اجباریپیش از هر صفحه theme/identity.ts را بساز:- brand: نام و لوگو (داکت لوگوی بالا)- dock.menu: آیتم‌های منوی داخل داکت (نام، برچسب، مسیر؛ آیتم‌های گروه‌پذیر name دارند مثل "shop:products")- dock.search (اجباری): method (page یا command-menu)، endpoint (مثلاً /search?q={query}؛ با method=page باید {query} داشته باشد)، minChars و placeholder. هر سه بدون استثنا لازم است و کلید جستجوی داک همین را باز می‌کند.- dock.mode / dock.sound / dock.clock / dock.groupable- dock.responsive: layout، align، size، labels، grouping، expandable، maxVisible، expandableBelow، mobileBehavior- channels: print، readAloud، sound، gestures و drag = "off"- alerts: position، success، error، destructive- login.arrival: نام نمایش ورود اختصاصی پروژه- تصمیم نمایش ورود: چه اطلاعاتی از کاربر نشان داده شود (نام و نام خانوادگی، تصویر پروفایل، لوکیشن/نقش/…) و کل صفحه چطور انیمیت شود## ۲.۵ پرسونا و لحن گفتمان — در قالب، با قرارداد TDS- پرسونا و لحن دستیار هر قالب فقط در `theme/persona.ts` و با `definePersona` از `@tokapps/tokens/persona` تعریف می‌شود. ابتدا ابزار `get_persona_presets` را بخوان و یکی از presetهای استاندارد را انتخاب کن (پیش‌فرض: `neutral-professional`)؛ پرسونای خارج از قرارداد نساز.- اگر کاربر دربارهٔ لحن نظری نداد، پیش‌فرض را پیشنهاد بده و تأیید بگیر؛ انتخاب را در گزارش نهایی بنویس.- جنسیت، سن، قومیت، لهجه و `aiDisclosure` در پرسونا ممنوع‌اند. `voice.autoplay` باید `false` و `voice.bargeIn`، `voice.textEquivalent` باید `true` بمانند. `voiceRef` فقط نام معنایی است (مثل `voice.calm-guide`)، نه شناسهٔ سرویس صدا.- دامنه‌های حساس (`health`، `finance`، `legal`، `crisis`) طنز و اموجی ندارند. دستیار هرگز خود را انسان معرفی نمی‌کند.- **پرسش اجباری از کاربر:** پیش از نوشتن `theme/persona.ts` در پروژهٔ جدید، این موارد را یک‌جا از کاربر بپرس و منتظر پاسخ بمان: (۱) preset (فهرست `get_persona_presets`)، (۲) دامنه (`domain`)، (۳) نام نمایشی فارسی و نقش (`role`)، (۴) زبان و شکل اعداد، (۵) خطاب (`address`) و میزان گرمی و طنز، (۶) فعال بودن کانال صوتی و `voiceRef` معنایی؛ (۷) رفتار گفتاری که توسعه‌دهنده از ایجنت می‌خواهد و با پاسخ او در `theme/persona.ts` ثابت می‌شود (کاربر نهایی آن را تغییر نمی‌دهد): سقف اموجی (۰ تا ۳)، میزان تملق (`forbidden` ممنوع، `acknowledge-only` فقط تصدیق احساس، `allowed` مجاز)، فهرست واژگان ممنوع، سقف کلمه در هر نوبت (۴۰ تا ۶۰۰) و سقف پرسش در هر نوبت (۱ تا ۳)؛ بدون پاسخ کاربر پرسونا ساخته نمی‌شود.- **قفل در AGENTS.md:** پس از ثبت پاسخ‌ها، بلوک پرسونا را با ابزار `render_persona_agents_md` در `AGENTS.md` پروژهٔ مقصد بنویس (بین نشانگرهای `tds-persona`). رابط کاربری را با همین پرسونا طراحی کن: لحن، خطاب، زبان و رفتار گفتاری در متن‌های رابط رعایت شوند.- **قفل چیدمان در AGENTS.md:** قواعد چیدمان پویا را با ابزار `render_layout_agents_md` در `AGENTS.md` پروژهٔ مقصد بنویس (بین نشانگرهای `tds-layout`). هر خروجی تولیدشده‌ای که کامپوننت رابط دارد (جدول، نمودار، فرم) پیش از نمایش با `validate_generative_layout` بررسی شود: ترتیب summary، widget، footnote، actions و چیدمان inline، side-panel یا full-canvas باید با قواعد بخواند و دلیل انتخاب ثبت شود.- **دقیق تعیین کن:** هر پاسخ را به یک مقدار معتبر قرارداد نگاشت کن و همان را در `definePersona` و گزارش نهایی بنویس. اگر کاربر دربارهٔ یک مورد نظری نداد، پیش‌فرض را پیشنهاد بده (`neutral-professional`) و تأیید بگیر؛ هیچ مقداری را بی‌صدا فرض نکن.## ۲. قالب پروژه — بعد از هویت، اجباریپوشهٔ theme/ را بساز (قرارداد کامل در THEME_TEMPLATE_CONTRACT از MCP):- theme/meta.ts: ProductThemeMeta با id، نام، hue/chroma/radiusScale/headingWeight، dock.slots (هر شش کلید true)، dock.groupable، dockClock، arrival (نام یکتا، نه نام‌های موجود orbit/constellation/launch/curtain/prism)، layout- theme/theme.css: فقط توکن‌های مجاز زیر [data-theme="tokapps"] (رنگ، شعاع، زمان‌های ورود)- theme/arrival.ts و arrival.css: نمایش ورود اختصاصی با ctx.part/ctx.phase/ctx.flyTo/ctx.land، فقط با توکن زمان و بدون رنگ خام- theme/index.ts: import تم پایه و CSS، و registerArrival(meta.arrival, arrival)- layout ریشه باید '../theme' را import کند و داک را از meta.dock و meta.dockClock بسازد.## ۳. ساخت یا آماده‌سازی پروژه[حالت پروژهٔ صفر]1. Next.js App Router با TypeScript بساز؛ name = tokapps-<slug>، private: true، type: module، packageManager = pnpm@10.18.0، اسکریپت‌های dev/build/start/lint (lint = tsc --noEmit).2. دیزاین سیستم را از رجیستری npm خصوصی نصب کن: `.npmrc` با رجیستری `https://rp.tokapps.ir/repository/npm-private/` و توکن `${NPM_TOKEN}` بساز، سپس پکیج‌های `@tokapps/*` را با نسخهٔ یکسان (`^0.2.2`) اضافه کن.   هسته: @tokapps/tuk، @tokapps/tokens، @tokapps/primitives، @tokapps/icons، @tokapps/next، @tokapps/theme-tokapps، @tokapps/patterns   اختیاری: @tokapps/motion، @tokapps/gestures، @tokapps/sound، @tokapps/accessibility   همچنین next ^16.4.0، react ^19.0.1، react-dom ^19.0.1 و devDependencies: typescript ^7.0.2، @types/node، @types/react، @types/react-dom.3. با npx -y pnpm@10.18.0 install نصب کن. اگر دسترسی گیت خطا داد، گزارش بده و متوقف نشو.4. فایل‌ها: next.config.ts با withTokapps و transpilePackages؛ tsconfig سخت‌گیرانه؛ types/modules.d.ts برای '*.css' و '@tokapps/tokens/css' و 'qrcode'؛ کپی فونت وزیر به public/fonts/vazir؛ app/globals.css با توکن‌های بوم و فونت.5. layout ریشه: TokappsFonts (basePath=/fonts/vazir)، TokappsProvider، tokappsHtmlProps روی <html>، TopBar لوگو، <main data-dock-reserve>، و ProductDock پایین.[حالت مهاجرت پروژهٔ موجود به TDS]پروژه را «قطعه‌قطعه» شیفت بده؛ یک‌جا بازنویسی نکن و هیچ‌وقت پروژه را در وضعیت نیمه‌کاره تحویل نده:1. اول در شاخهٔ جدا: بستهٔ TDS را نصب کن، theme/identity.ts و theme/ را بساز، و یک صفحهٔ «tsd-check» بساز که فقط TopBar و ProductDock و یک Button از کیت را نشان دهد. تا وقتی tsc و validate_agent_output پاس نشده، به صفحه‌های اصلی دست نزن.2. سپس پوستهٔ سراسری را جایگزین کن: نوار ناوبری بالای قدیمی و فوتر منوی قدیمی را حذف کن، TopBar و ProductDock را در layout ریشه بگذار و data-dock-reserve را به محتوای هر صفحه بده. ناوبری صفحه‌ها را به بخش‌های داکت منتقل کن (identity.dock.menu).3. بعد لایهٔ استایل را کمرنگ کن: متغیرهای رنگ پروژهٔ قدیمی را به توکن‌های معنایی --tds-* نگاشت کن و هر رنگ خام/هگز باقی‌مانده را حذف کن (مپ: رنگ متن/پس‌زمینه/حاشیه/اکشن/بازخورد). فونت قدیمی را با وزیر عوض کن و dir را درست کن.4. پس از آن صفحه‌به‌صفحه برو: هر صفحه را با کامپوننت‌های کیت و الگوها بازنویسی کن (کامپوننت قدیمی همان صفحه را کنار بگذار، نه همهٔ کامپوننت‌های مشترک را یک‌جا).5. مهاجرت ورود: فرم ورود قدیمی را با AuthFlow از @tokapps/patterns عوض کن و نتیجهٔ ورود موفق را به signInSuccess وصل کن؛ نشست کاربرِ از قبل لاگین‌شده را پس از reload با setTdsSession(user) بی‌صدا بازیابی کن (بدون نمایش ورود).6. مهاجرت پخش صدا: هر پخش‌کنندهٔ محلی پروژه (پخش‌کنندهٔ ساخته‌شده با <audio> یا کتابخانهٔ دیگر، کوچک‌کنندهٔ اختصاصی) را با پخش‌کنندهٔ داک عوض کن — فهرست اپیزودها با Podcast از @tokapps/patterns و بقیهٔ پخش‌ها با playOnDock از @tokapps/tuk/dock؛ پخش باید با تغییر صفحه ادامه پیدا کند. کلیدهای کوچک‌کردن/دریافت/اشتراک/سرعت را از خود پخش‌کننده بگیر.7. در پایان، کد مرده و استایل قدیمی بی‌استفاده را حذف کن، ولی هیچ فایل خارج از دامنهٔ مهاجرت را تغییر نده.## ۴. صفحه‌ها (پس از هویت و قالب)- صفحه‌ها را با کامپوننت‌های TUK و primitives بساز (Stack، Grid، Heading، Text، Card، Badge، Button، Table، Breadcrumb و الگوها). رنگ خام و هگز ننویس.- هر Button کانال چاپ هویت پروژه را بگیرد ({...buttonChannels}).- هر صفحه data-dock-reserve داشته باشد.- اگر نیاز به رویداد/کار روی زمان هست، از Calendar با آرایهٔ CalendarItem استفاده کن و همان آرایه را به ProductDock (calendarItems) هم بده تا ساعت داک همان تقویم را باز کند.- پاپ‌آپ جستجو: یک کامپوننت کلاینت ('use client') بساز که هم ProductDock را رندر کند و هم CommandMenu را؛ ProductDock روی onSearch کمیندمنو را باز می‌کند، placeholder و minChars از identity.dock.search، results محلی یا سروری با onQueryChange روی endpoint، و hotkey="mod+k" روشن بماند. اگر method=page است، onSearch به همان endpoint با {query} می‌رود.- برای جریان ورود: AuthFlow + signInSuccess + نمایش ورود theme/arrival.ts؛ و در theme/arrival.ts در پردهٔ ظهور اطلاعات واقعی کاربر (ctx.user.name، ctx.user.avatarUrl با ctx.image، و ctx.user.meta) را نشان بده و در پردهٔ پرواز با ctx.flyTo تصویر پروفایل را روی آیکون حساب داک بنشان.- اگر صفحه صدا/پادکست/موسیقی دارد: فهرست اپیزودها با <Podcast> از @tokapps/patterns و پخش‌های پراکنده با playOnDock از @tokapps/tuk/dock. پخش‌کنندهٔ محلی، <audio>، new Audio() و کتابخانهٔ پخش ممنوع؛ کوچک‌کردن (دیسک/زبانه)، صف، سرعت، دریافت/اشتراک و Media Session از خود پخش‌کننده می‌آید و هویت پخش‌کننده (اندازه، حرکت، نوار پیشرفت، جمع‌شدن) از meta.dockPlayer همان تم.## ۵. اعتبارسنجی (الزامی)1. npx -y pnpm@10.18.0 exec tsc --noEmit بدون خطا.2. validate_agent_output را روی همهٔ فایل‌های تغییرکرده (app، components، theme، middleware) اجرا کن؛ خطاها را برطرف کن و دوباره اجرا کن تا approved شود. validate_rtl، validate_accessibility و validate_responsive_behavior را هم اجرا کن.3. dev server را بالا بیار (npx -y pnpm@10.18.0 exec next dev) و در مرورگر بررسی کن: داکت پایین، داکت لوگوی بالا، breadcrumb، ورود تا نمایش ورود موفق (المنت [data-tds="arrival"])، و تقویم.4. کنسول و لاگ سرور را بررسی کن؛ خطای قرمز نباید بماند.## ۶. گزارش نهایی- مسیر پروژه، فهرست پکیج‌ها با نسخه، و آدرس پیش‌نمایش.- نتیجهٔ tsc و validate_agent_output (approved یا خطاها).- اگر مهاجرت بود: فهرست صفحه‌هایی که مهاجرت کردند و صفحه‌هایی که ماندند.- اگر پروژه صدا داشت: کدام صفحه با Podcast یا playOnDock پخش می‌کند و تأیید اینکه هیچ پخش‌کنندهٔ محلی/<audio> در کد نمانده.- هر کاری که انجام ندادی یا مانع ماند (مثلاً دسترسی گیت) را صریح بنویس.- چیزهایی که نمایشی‌اند (ورود، داده‌ها) را فهرست کن.## ویرایشگر متن غنی و پارامترهای داینامیک (الزامی)- متن غنی (قالب‌بندی، تصویر، فایل، پخش صوت) فقط با `RichTextEditor` یا `InlineEditor` از `@tokapps/editor` ساخته شود. ساختن ویرایشگر با `contenteditable`، `document.execCommand`، quill، tinymce، slate، lexical یا `@tiptap/*` مستقیم در کد محصول ممنوع است (گیت `editor/kit`).- شماره تماس، ایمیل، نشانی، قیمت و نام شرکت یا محصول در متن رابط ثابت نوشته نشود؛ با `DynamicText` (`{{key}}`) یا `<Param k="…" />` از `@tokapps/tuk/params` نمایش داده شود تا تغییر در ادمین همه‌جا اعمال شود (گیت `content/dynamic-params`).- صوت داخل متن مقاله فقط با بلوک `::player{param=…}` یا `RichTextEditor` و پخش روی داک انجام شود؛ `<audio>` محلی ساخته نشود.