talizen

name	talizen
description	Guidance for Talizen platform apps. Read this skill before editing project files or giving Talizen-specific advice (talizen.config.ts, /page routes, CMS/form, Tailwind v4, SEO/metadata, importMap, platform tools). Examples: "Build a website for a coffee shop", "Create an About page", "Preview this page", or "Preview this component". Not required for greetings or non-project chat.

Talizen

Talizen apps are React-based websites with file-based routes under /page, a root talizen.config.ts, Tailwind v4 styling, and platform APIs for CMS, forms, metadata, import maps, linting, previews, and versioning.

Use this file for the non-negotiable platform rules and the default workflow. Use the references/*.md files for detailed examples.

Hard Rules

• Talizen is not a standard browser SPA or Next.js app. Do not introduce react-router-dom, next/link, next/router, next/navigation, getStaticProps, or getStaticPaths.
• Pages live in /page as .tsx React components. Keep reusable UI in /component or another shared components directory.
• Use native anchors such as <a href="/about">...</a> for navigation. Do not import Link from talizen, next/link, or router libraries.
• Prefer getServerSideProps(context) for route params and first-render data. Read dynamic params from context.params; do not use client-side param hooks when SSR params are available.
• Do not proactively create *.canvas.ts or *.canvas.tsx files. They are generated by the platform. Edit existing canvas files only when the user explicitly asks.
• Use Tailwind v4 utility classes for styling. Do not add inline style props or ad-hoc <style> tags in page components.
• Use metadata for SEO instead of custom seo fields or raw <title> / <meta name="description"> tags.

Default Workflow

1. Locate the project root and read talizen.config.ts when configuration, imports, SEO, custom code, or site-level styling may be involved.
2. If the project contains AGENTS.md, read it before editing and follow it as primary local guidance.
3. Inspect the relevant page/component/schema files before changing code.
4. Before modifying files in the Talizen AI assistant, create a version with create_version so the change can be rolled back.
5. Apply focused edits, preferably with diff_patch_file in the Talizen AI assistant.
6. Run lint whenever page or component code changed.
7. After successful edits, create one final version with create_version. A task should create at most two versions: before and after the change.

If the user asks only for a component, make it visible in a page whenever possible, especially when they ask to preview it. A standalone component cannot render as a site page by itself.

When importing an existing project into Talizen, preserve the full source experience: pages, content, behavior, and design fidelity unless the user asks for design changes.

Routing

Routing is derived from /page file names by Talizen conventions:

• /page/Index.tsx -> /
• /page/About.tsx -> /about

For non-Index pages, do not guess kebab-case routes. Prefer the lowercase canonical path returned by lint/validation; for example, /page/BlockElementsPage.tsx should be linked as /blockelementspage.

Files like /page/XXXX.canvas.tsx are canvas preview entries used by the platform editor, not normal route files to generate by hand.

CMS

Use talizen/cms in getServerSideProps, then pass plain serializable props to the page component.

• Use listContents for lists, getContent for single items, and getContentWithPrevNext for adjacent content.
• Treat CMS data as optional; use optional chaining and user-friendly fallbacks.
• Return notFound: true when content does not exist. Use redirect when access or routing should change.
• Read /types/cms.d.ts for generated collection shapes.

For examples, see references/CMS.md.

Forms

Use submitForm from talizen/form for platform form submissions.

• Read /types/form.d.ts before writing form code and keep submitted payloads aligned with the generated type.
• Use the stable form key from the editor, not the display name.
• In Talizen AI tools, use list_form() to inspect forms and create_form({...}) to create new forms.

For schema details and examples, see references/FORM.md.

Metadata

Talizen uses a two-level metadata model:

• Site-level metadata in talizen.config.ts
• Page-level export const metadata or export async function generateMetadata from each page component file

Use metadata.openGraph for Open Graph data, metadata.keywords for keyword lists, and absolute URLs for Open Graph media.

For complete fields and migration examples, see references/SEO.md.

Sitemap

Use a root-level /sitemap.ts file for sitemap generation. Its authoring rules follow Next.js sitemap.ts: export a default function that returns sitemap entries or a promise of sitemap entries.

• Keep /sitemap.ts at the project root, not under /app.
• Use TALIZEN_PUBLIC_SITE_URL environment variable for the site URL.
• Use listContents from talizen/cms when entries depend on CMS list or detail page data.
• Read /types/cms.d.ts before referencing collection fields.

For complete rules and a minimal example, see references/SITEMAP.md.

Import Map

There are two import map views:

• get_import_map() returns the final effective runtime import map, including platform-provided modules and user-defined entries.
• talizen.config.ts contains only user-defined extra imports. Edit importMap.imports there when adding or changing third-party dependencies.

Keep import maps clean:

• Only add packages that are actually used.
• Prefer esm.sh unless compatibility requires another CDN.
• Do not add react, react-dom, or talizen; the platform already provides them.
• Talizen's compiler supports Vite-style local asset queries for relative imports: import assetUrl from "./asset.ext?url" returns a browser-accessible Blob URL, and import source from "./file.ext?raw" returns the original file contents as a string. Use these for worker source, WASM/worker helper scripts, and other local assets that need URL or raw-string semantics.
• For React-dependent esm.sh packages, use ?external=react so they use the host React copy, for example https://esm.sh/framer-motion@12.34.5?external=react.
• If you see duplicate-React symptoms such as Cannot read properties of null (reading 'useState') with both react.mjs and an esm.sh package in the stack, add ?external=react to that package URL, including React wrapper subpaths such as swiper/react.

Package Types

Use fetch_module_types(specifier) only when exact package signatures are needed, a less common package/subpath is involved, the effective URL/version changed, the user explicitly asks to verify the API, or lint/typecheck suggests the quick reference is stale.

Do not fetch module types for common packages already covered by model knowledge, such as react.

Keep package declarations separate from generated project types:

• fetch_module_types("specifier") describes package exports and helper signatures, such as talizen/cms or talizen/form.
• /types/cms.d.ts and /types/form.d.ts describe generated project schemas and payload fields.

Styling

Talizen uses Tailwind CSS v4.

• Use utility classes for component styling.
• Use /index.css only for site-level Tailwind source such as @theme, @utility, and base layers. Do not add arbitrary extra CSS files for one-off component styling.
• When adding color transitions, drive the color from one source to avoid double hover transitions. Either let children inherit the parent color or control the child color with a single hover/group-hover rule.

For site CSS conventions, see references/CSS.md.

Components And Effects

For slideshow or carousel requirements, follow references/CAROUSEL.md.

For shadcn/ui-style registry components:

• Configure components.json registries first.
• Use shadcn_search_items, shadcn_list_items, and shadcn_install_item.
• Common registries are @spell, @fancy, and @react-bits.
• For polished visual effects, animations, particles, cursor effects, text animations, hover effects, or creative backgrounds, prefer searching component registries before implementing custom effects.
• Ensure installed animated layers do not block content, reduce readability, or break responsive layouts.

Minimal components.json example:

{
  "registries": {
    "@spell": "https://spell.sh/r/{name}.json",
    "@fancy": "https://fancycomponents.dev/r/{name}.json",
    "@react-bits": "https://reactbits.dev/r/{name}.json"
  }
}

talizen.config.ts

Use export default with a plain object. Do not import packages in this file except type-only imports such as import type { Metadata } from "talizen". Do not use defineConfig from talizen/config.

talizen.config.ts can define:

• importMap.imports for user-defined third-party dependencies
• metadata for global SEO
• customCode.head and customCode.body for small analytics, verification, or script snippets not covered by structured metadata

Do not duplicate metadata in customCode; prefer structured metadata whenever the field fits.

Reply Rules

The end user of the Talizen AI assistant is typically non-technical:

• Do not expose raw code snippets unless explicitly requested.
• Do not show internal tool outputs such as diff_patch_file, lint, or create_version.
• Describe what changed on the site, how the page behaves, and what the user can do next instead of focusing on implementation details.

References

• references/CMS.md for CMS fetching patterns
• references/FORM.md for form payloads and schema creation
• references/SEO.md for metadata fields and SEO migration
• references/CSS.md for Tailwind v4 site CSS conventions
• references/CAROUSEL.md for carousel/slideshow setup