Kural AI
AI vibe coding operating manual
AI கருவிகளுக்கான முழு உருவாக்க வழிமுறை
End-to-end instructions for any AI coding tool to reproduce Tamil DS setup, implementation style, Tamil-first content, accessibility and final visual quality. Stack: Next.js 16 · React 19 · Tailwind v4 · @base-ui/react 1.4.1.
எந்த AI கருவியும் Tamil DS திட்ட அமைப்பு, செயலாக்க முறை, தமிழ் உள்ளடக்கம், அணுகல்தன்மை மற்றும் காட்சி தரத்தை ஒரேபோல் உருவாக்க பின்பற்ற வேண்டிய முழுமையான வழிமுறை.
This page is the full brief, not a suggestion.
Share this URL with any AI tool before it touches Tamil DS. It covers orientation, setup, file locations, component choices, layout recipes, Tamil content quality, accessibility, visual QA and verification. The page is self-contained, so the AI can follow it even when it cannot read this repository.
Portable Context
These are the rules another AI must follow from the URL alone. Repository access improves execution, but it is not required to understand the design direction.
Project identity
Tamil DS is a Tamil-first design system for polished public-service, civic, AI-assisted and product interfaces.
Output goal
The output must feel production-ready: clear workflow, strong hierarchy, real content, accessible controls and refined visual composition.
Design language
Quiet premium SaaS quality adapted for Tamil public-service use: white space, restrained surfaces, strong typography, subtle borders, token shadows and meaningful UI mockups.
Tamil-first rule
Visible UI defaults to Tamil for Tamil/public-service contexts. English is reserved for proper nouns, acronyms, code, package names and explicit bilingual requests.
Component rule
Use design-system primitives for buttons, cards, badges, inputs, tables, overlays, calendars and navigation. All primitives are built on @base-ui/react 1.4.1 — NOT Radix UI. State attributes use data-checked/data-unchecked/data-open/data-disabled, not aria-checked variants.
Tailwind v4 rule
This project uses Tailwind CSS v4. Config is CSS-first via @theme {} blocks in globals.css — there is NO tailwind.config.js. Do not reference tailwind.config.ts or the old config format.
React 19 rule
The project runs React 19 and Next.js 16 with App Router. Use Server Components by default. Add 'use client' only when hooks, events or browser APIs are needed.
Tamil line-height rule
CRITICAL: Never apply line-height: 1.8 (or leading-7/leading-relaxed) on a container element that wraps form controls (buttons, inputs, checkboxes, switches, labels). Apply Tamil line-height only on text content nodes: p, li, span, td, blockquote. Setting it on a wrapper like CardContent with lang=ta bleeds into all child controls and distorts their layout.
font-tamil scope rule
CRITICAL: Do not put lang=ta or className=font-tamil on a wrapper element that contains interactive controls. Apply these only to the specific text elements (Label, p, span) that render Tamil script. The CSS selector :lang(ta)/.font-tamil must not match buttons, inputs, checkboxes or switches.
Accessibility rule
Keyboard, focus, contrast, aria labels, skip links, text resizing/contrast controls and viewport-safe floating panels are part of the required output. Interactive primitives (Checkbox, Switch, RadioGroup, Slider) manage their own focus ring — do not override with global :focus-visible border-radius.
Theming rule
ZERO new implementation needed for light/dark/theming. ThemeProvider (next-themes 0.4.6) is already in layout.tsx with defaultTheme='light' and enableSystem. Dark mode is toggled by adding the .dark class to <html>. ALL color tokens auto-swap via CSS custom properties in globals.css :root (light) and .dark {} blocks. Use ONLY bg-background, text-foreground, bg-card, bg-primary, text-muted-foreground, border-border etc. Never hardcode oklch/hex/rgb values in new components.
Verification rule
The final work must pass lint, type checks and production build when code access is available. Without code access, the AI must provide implementation-ready code and QA checklist.
How to Use This URL
1. Share the link
Give the AI this page URL before the task. Tell it to treat the page as the full brief.
2. State the target
Name the exact page, component, block or design-system area that must be created or fixed.
3. Mention access level
If the AI has repo access, ask it to edit files. If not, ask for implementation-ready code and a file plan.
4. Require verification
Ask for lint, type-check and build results when code access exists, or a manual QA checklist when it does not.
Using the Agent Skill
The `@tamildesignsystem/react` package includes a reusable agent skill at skills/tamil-ui-design/SKILL.md. Use it when asking an AI coding agent to build Tamil-first UI. It covers Tamil typography, mobile checks, component rules, accessibility, and layout safety.
Technology Stack
Exact installed versions as of the last update. Use these when generating imports, choosing APIs, and verifying compatibility. Do not guess versions.
Next.js
16.2.6
App Router, React Server Components, Turbopack dev server. Use 'use client' only when hooks/events are needed. Server components are the default.
React
19.2.4
React 19. Concurrent rendering, useFormState/useFormStatus available. No legacy class components.
Tailwind CSS
4.3.0
BREAKING: Tailwind v4. Config is CSS-first via @theme {} in globals.css — no tailwind.config.js. Use @theme to define tokens. Utilities like bg-primary, text-foreground resolve from CSS custom properties.
@tailwindcss/postcss
4.3.0
PostCSS plugin for Tailwind v4. Replaces the old tailwindcss postcss plugin.
@base-ui/react
1.4.1
CRITICAL: Base UI replaces Radix UI for all primitives — Checkbox, Switch, RadioGroup, Slider, Select, Dialog, Popover, Tooltip, Accordion, etc. Use @base-ui/react/<component> imports. State attributes are data-checked, data-unchecked, data-disabled, data-open — NOT aria-checked/aria-expanded style Radix variants.
@tamildesignsystem/react
latest
Tamil-first React components, design tokens, and agent guidance for building accessible Tamil interfaces.
shadcn
4.7.0
CLI for scaffolding components. Run: npx shadcn@latest add <component>. Components are placed in src/components/ui/.
lucide-react
1.14.0
1100+ icons available. Always check lucide.dev for exact icon names. Icon components accept className and size props.
framer-motion
12.38.0
Motion library. Use motion.div, AnimatePresence, useAnimation. Respect prefers-reduced-motion.
tw-animate-css
1.4.0
CSS animation utilities for Tailwind v4. Provides animate-in, animate-out, fade-in, zoom-in etc.
next-themes
0.4.6
ThemeProvider for dark/light mode. Access with useTheme() hook. resolvedTheme for SSR-safe reads.
sonner
2.0.7
Toast notifications. Use toast(), toast.success(), toast.error(). Wrap app in <Toaster /> component.
TypeScript
5.9.3
Strict mode enabled. Use type imports. Prefer interface for component props, type for unions/intersections.
cmdk
1.1.1
Command palette primitive. Used for command menus and search overlays.
embla-carousel-react
8.6.0
Carousel engine. Used inside the Carousel component primitive.
react-day-picker
10.0.0
Calendar/date picker. Used inside the Calendar component primitive.
date-fns
4.1.0
Date utility library. Prefer date-fns over moment.js or native Date manipulation.
tailwind-merge
3.5.0
Class merging. Always use cn() from src/lib/utils.ts which wraps clsx + twMerge.
html-to-image
1.11.13
DOM-to-image utility used in export/screenshot features.
react-resizable-panels
4.11.0
Resizable panel layouts. Used for split-pane views.
Theming, Dark Mode & On-Demand Theming
The complete theming foundation is already built. Light mode, dark mode, high contrast, font scaling, spacing scaling and on-demand palette overrides all work out of the box. Do not add new providers, config files or theming libraries. Just use the token utilities.
How dark mode works
next-themes adds/removes the .dark class on <html>. Tailwind v4 custom variant `@custom-variant dark (&:is(.dark *))` in globals.css maps .dark to all dark: utilities. No JS theming logic is needed in components — just use token utilities.
Use dark:bg-card, dark:text-foreground etc. only when a component needs an explicit dark override. Most surfaces are handled automatically by tokens.
ThemeProvider config (layout.tsx)
attribute='class' applies the theme as a CSS class. defaultTheme='light' — project defaults to light mode. enableSystem — respects OS prefers-color-scheme when user has not set a preference. disableTransitionOnChange={false} — smooth transitions between modes.
Do NOT change these props unless building a new app. suppressHydrationWarning is required on <html> and <body> to suppress next-themes hydration mismatch.
Light mode tokens (:root)
Defined in globals.css :root {}. Key values: --background: oklch(0.99 0 0) [near white], --foreground: oklch(0.145 0 0) [near black], --card: oklch(1 0 0), --primary: var(--brand) [violet oklch(0.56 0.18 285)], --muted: oklch(0.965 0.001 260), --border: oklch(0.922 0.004 260).
Always reference tokens via Tailwind utilities: bg-background, bg-card, bg-primary, text-foreground, text-muted-foreground, border-border, ring-ring.
Dark mode tokens (.dark)
Defined in globals.css .dark {}. Key values: --background: oklch(0.10 0 0) [deep dark], --foreground: oklch(0.93 0 0) [near white], --card: oklch(0.135 0.005 260), --primary: var(--brand) [lighter violet oklch(0.70 0.16 285)], --muted: oklch(0.197 0.006 260), --border: oklch(1 0 0 / 0.08) [semi-transparent].
Shadows auto-scale too: dark mode uses higher opacity (0.24–0.56) to remain visible on dark surfaces.
High contrast mode
CSS class .a11y-high-contrast on <html> overrides: --background→white, --foreground→black, --border→black, --primary→black (light) or inverted (dark). Applied by AccessibilityProvider from user preferences stored in localStorage.
Works on top of both light and dark modes. No extra implementation needed — token cascade handles it.
On-demand theming (custom palette)
To theme a page or section differently, override tokens on a scoped element: <div style={{'--primary': 'oklch(0.60 0.20 160)', '--brand': 'oklch(0.60 0.20 160)'} as React.CSSProperties}>. All child primitives (Button, Badge, Ring, Progress) inherit the override automatically.
Do NOT create new CSS classes for custom themes. Override CSS custom properties inline or via a wrapper className that sets CSS vars.
Theme toggle (SiteHeader)
const { resolvedTheme, setTheme } = useTheme(). Toggle: setTheme(resolvedTheme === 'dark' ? 'light' : 'dark'). Use resolvedTheme (not theme) to avoid SSR mismatch — resolvedTheme is always 'light' or 'dark', never 'system'.
Sun/Moon icon pair: Sun rotates/scales out in dark, Moon rotates/scales in. CSS classes: dark:-rotate-90 dark:scale-0 and dark:rotate-0 dark:scale-100.
Accessibility provider (a11y)
AccessibilityProvider wraps the app inside ThemeProvider. Applies HTML classes: a11y-text-{sm|md|lg|xl|2xl} for font scaling, a11y-spacing-{compact|normal|relaxed}, a11y-high-contrast, a11y-dyslexia, a11y-reduced-motion. State persisted to localStorage under key 'tamilds-accessibility'.
Use useAccessibility() hook to read/set these preferences in any client component. Context is already provided — no setup needed.
Correct token usage patterns
✅ bg-background, bg-card, bg-muted, bg-primary, bg-secondary, bg-destructive, bg-success, text-foreground, text-muted-foreground, text-primary-foreground, border-border, ring-ring, shadow-sm. ❌ Never: bg-white, bg-gray-*, text-black, border-gray-*, custom oklch() hardcoded in component className.
Exception: decorative surfaces (hero gradients, illustration fills) may use specific oklch values. All interactive and structural surfaces must use tokens.
Theming anti-patterns to avoid
❌ Do not add a second ThemeProvider. ❌ Do not set defaultTheme='system' — project default is light. ❌ Do not use theme === 'dark' for conditional rendering — use CSS dark: variants instead. ❌ Do not add tailwind.config.js darkMode setting — Tailwind v4 uses @custom-variant in globals.css.
❌ Do not import or use @radix-ui/themes or any other theming library. The entire theming stack is next-themes + CSS custom properties.
Non-negotiables for theming
- Never hardcode oklch/hex/rgb colors in component className strings — always use token utilities.
- Never add a second ThemeProvider or change defaultTheme from 'light'.
- Never use theme === 'dark' for conditional JSX — use CSS dark: Tailwind variants.
- Always use resolvedTheme (not theme) when reading the current mode to avoid SSR mismatch.
- On-demand palette changes: override CSS custom properties inline, not with new CSS classes.
Repository Map
Use this when the AI has code access. Without code access, this still tells the developer where the generated implementation should be placed.
Routes
src/app/(docs), src/app/(preview)
Docs routes live in (docs). Block previews live in (preview). Add new page.tsx files inside the correct route group.
Navigation
src/lib/nav.ts
Add docs pages to docsNav. Keep hrefs route-group agnostic, for example /ai/vibe-coding.
UI primitives
src/components/ui
Use these first. Do not recreate core controls with custom div/button markup. All built on @base-ui/react.
Docs primitives
src/components/docs
Use PageHeader, ComponentPreview, DoDont, ComponentAnatomy and PropsTable for documentation pages.
Blocks
src/components/blocks
Large page examples and case-study experiences belong here.
Layout
src/components/layout
Sidebar, docs shell and global navigation patterns.
Tokens
src/app/globals.css
Tailwind v4 CSS-first config via @theme {}. Theme colors, shadows, radius, spacing and global surfaces all defined here. Prefer tokens before hardcoded colors.
Utilities
src/lib/utils.ts
Use cn() for class merging (clsx + tailwind-merge).
End-to-End Workflow
0
Confirm the task type
Classify the request: component docs, component primitive, block/page, case study, accessibility fix, content update, or visual polish.
1
Load the portable rules
Use this page as the complete instruction source. If the workspace also has AGENTS.md or framework docs, read them as extra context, not as a requirement.
2
Inspect local precedent
Use rg to find similar pages/components. Copy the local pattern before inventing a new one.
3
Identify write scope
List the files that need edits. Ignore unrelated dirty files. Never revert user work.
4
Choose primitives
Select the Tamil DS primitives and docs helpers needed. If a primitive exists, use it.
5
Draft content before layout
For public or Tamil pages, define real content and Tamil labels before composing UI.
6
Build the first viewport
Make the first screen useful and complete: clear title, action, visual anchor and trust signal.
7
Build the rest as reusable sections
Use repeated section patterns, consistent spacing and one purpose per section.
8
Accessibility pass
Check focus states, aria-labels, keyboard paths, contrast and responsive text wrapping.
9
Visual QA pass
Look for clipped pills, uneven cards, nested cards, hardcoded off-brand colors and overloaded actions.
10
Verify
Run targeted eslint, npx tsc --noEmit, and npm run build for broad route or primitive changes.
Command Protocol
Install dependencies
npm installUse only when dependencies are missing or the repo is fresh.
Start dev server
npm run devUse for interactive browser review. Turbopack is the default bundler.
Targeted lint
npx eslint <changed-files>Run after any code edit.
Type check
npx tsc --noEmitRun before final response.
Production build
npm run buildRun for route, layout, primitive, block and docs-nav changes. All 91 routes must appear in the build output.
Add component (shadcn)
npx shadcn@latest add <component>Scaffolds component into src/components/ui/. Always review the generated file — it uses @base-ui/react primitives.
Search files
rg --filesPrefer rg over slow directory listing.
Search text
rg "pattern" pathUse before editing to find all affected surfaces.
Check Tailwind token
rg "--your-token" src/app/globals.cssAll tokens live in globals.css @theme {} blocks. No tailwind.config.js exists.
Component Decision Tree
Action
Button, Icon Button, Link
Use Button for actions, Link for navigation, icon size only with aria-label.
Information
Card, Badge, Table, Alert
Use Card only for repeated contained items, not full page sections.
Input
Input, Textarea, Select, Checkbox, Radio, Switch, Slider, Calendar
Pair inputs with labels and visible validation states.
Navigation
Breadcrumb, Tabs, Pagination
Navigation must indicate current location/state and support keyboard use.
Overlay
Dialog, Alert Dialog, Sheet, Popover, Tooltip, Dropdown Menu
Use overlay only when the task requires temporary context. Do not hide primary workflows.
Documentation
ComponentPreview, DoDont, ComponentAnatomy, PropsTable
Docs examples must match the actual component variant and data.
AI surface
Chat panel, prompt cards, suggestion buttons
Keep composer visible, body scrollable and suggestions practical.
AI prompt composer
Inline prompt bar with Plus, Settings2, Mic icons
Use the Tamil DS prompt layout: Plus + Settings2 on left, input in center, Mic + submit on right. Add focus-within ring.
Skills tags
Clickable slash-command lozenges
Render as rounded-md border bg-muted/50 tags with a / prefix. Clicking a tag should set the input value to the slash command and focus the input field.
Kural AI chat
Static chat section or floating chat widget
Use KuralAIChatSection for embedded page sections and FloatingKuralChat for floating assistants. Both must include skill tags and inline prompt layout.
Page Recipes
Docs component page
PageHeader -> variants preview -> sizes/states -> anatomy -> props -> best practices -> accessibility.
Use ComponentPreview for live examples. Do/don't examples must not reuse identical UI for both sides.
Foundation page
PageHeader -> token explanation -> scale examples -> usage rules -> common mistakes.
Avoid decorative examples that do not teach token use.
Public block page
Header -> compact hero -> search/action surface -> trust/proof -> service sections -> support -> CTA -> footer.
First viewport must be usable, not just impressive.
Government page
Tamil-first header -> service search -> departments -> schemes -> documents -> Kural AI chat -> help/contact -> accessibility toolbar.
Use official content structure. Integrate Skills Tags and Inline Prompt in chat sections. Avoid generic SaaS marketing language.
AI page
Purpose -> operating rules -> recipes -> prompts -> verification -> failure modes.
Make instructions copyable and tool-agnostic.
Case study
Problem -> audit -> design decisions -> IA -> components -> accessibility -> delivery checklist.
Show what changed and why, not only the final design.
Tamil site (end-to-end)
lang=ta root -> font-tamil class -> safe line-heights -> bilingual nav -> Kural AI chat -> accessibility controls -> Tamil typography safety.
See the full Tamil Site Building Guide sub-page for comprehensive step-by-step instructions.
Core Operating Rules
Output Design Contract
This is the visible quality bar for generated UI. Any AI using this page must satisfy these output rules before considering the work complete.
First screen
The first viewport must communicate the product/page purpose, primary workflow and trust signal without requiring scroll.
Use compact hero sizing, one strong heading, one primary action, one useful secondary action and a real UI surface such as search, service cards, dashboard, form or chat.
Hierarchy
The UI must be scannable in 5 seconds.
Use clear section labels, strong h1/h2 contrast, readable paragraph width, consistent card titles and predictable action placement.
Spacing
Spacing must feel deliberate, not stretched.
Use smaller vertical rhythm for dense civic/product pages, larger rhythm for storytelling sections, and remove empty bands that do not contain useful content.
Cards
Cards must represent real repeated objects or contained tasks.
Do not use cards as page wrappers. Keep badges inside padding, align icons with title text, and make card heights consistent within a row.
Controls
Controls must look like a coherent product system.
Use system Button, Input, Select, Tabs, Pagination and overlay primitives. Avoid one-off shadows, random colors, custom focus rings or mismatched radii.
Tamil output
Tamil copy must be visually tested as real UI text.
Use generous line-height, avoid cramped chips, prevent long labels from clipping, and keep public-service tone official and useful.
Responsive output
Mobile, desktop and short-height browser states must all feel complete.
No floating chat window, popover, nav, pill, hero heading or card may be cut off. Body areas scroll; composers and primary actions stay reachable.
Final delivery
The final output must include a clear edit summary and verification evidence.
List changed files, describe UI behavior/design changes, state lint/type/build results, and call out any remaining risk honestly.
How to Produce the Best Design Output
Use this as the visible design reference for AI-generated pages, blocks and product surfaces. The goal is a production-ready Tamil DS result: useful first viewport, real workflow content, token-based styling, accessible controls and no clipped Tamil UI.
Reference intent
Produce a finished product surface, not a prompt illustration.
The output should look like a live civic SaaS product: useful first screen, real data/content, restrained visual polish, and obvious next actions.
Composition
Use a strong editorial grid with product density.
Prefer max-w-7xl containers, two-column hero only when the right side is a real UI surface, and section bands that flow without card-wrapping the whole page.
First viewport
Show the main workflow before scroll.
Include navigation context, h1, concise supporting copy, primary action, secondary action, trust/status cue, and a real interactive-looking surface such as search, form, table, dashboard, document, calendar, service panel or chat.
Typography
Use type to create calm authority.
Hero h1 should be confident but viewport-safe. Section h2s should be compact and readable. Body copy should stay 65-75 Latin characters or 50-65 Tamil characters per line where possible.
Tamil typography
Tamil must be tested as the primary language.
Use generous line-height, avoid tiny uppercase-style labels, allow wrapping in chips/buttons, and keep Tamil phrases natural instead of transliterated English.
Color
Use tokens and one purposeful accent.
Start from bg/background/card/muted/foreground/border tokens. Add a single brand accent for primary actions and status. Avoid leftover blue/purple gradients from unrelated pages.
Surfaces
Separate page structure from object containers.
Sections are full-width bands or plain layouts. Cards are only for repeated entities or contained tasks. Never put a large page section inside a card.
Cards
Cards must be aligned and content-real.
Use rounded-md, border, bg-card/white, subtle shadow, 20-28px padding, consistent title placement, baseline-aligned icons, and no clipped badges or pills.
Controls
Controls should feel native to Tamil DS.
Use Button, Input, Select, Tabs, Dialog, Sheet, Popover, Tooltip and Table primitives. One filled primary action per section; secondary actions use outline, ghost, or text-link styling.
Icons
Icons clarify function, not decoration.
Use lucide icons at consistent sizes. Pair icons with labels unless the control is universally recognizable and has aria-label.
Motion
Motion is optional and functional.
Use motion only for state changes, entry polish, disclosure, chat panels or progress. Respect reduced motion and avoid constant decorative movement.
Imagery
Use real or product-relevant visuals.
For websites and blocks, use actual product/place/object imagery, generated bitmap assets, or a real UI mockup. Avoid generic abstract blobs, empty SVG art, and dark cropped stock imagery.
Density
Match density to the job.
Government, dashboard, CRM and admin surfaces should be compact and scannable. Marketing pages can breathe more, but must still show a real workflow.
Responsive
Every viewport must preserve the core task.
At 375px width and short laptop heights, no nav, hero, pill, floating chat, popover, or CTA can obscure or clip the primary content.
Final polish
Run a visual defect pass before claiming done.
Check spacing rhythm, card row heights, text wrapping, contrast, focus rings, empty states, hover states, scroll containers, and route/build output.
Style-output reference prompt
Use this style-output reference before generating UI.
The output should look like a finished Tamil DS product surface, not a decorative mockup.
Style requirements:
1. Build a useful first viewport with navigation context, h1, short copy, one primary action, one secondary action, trust/status cue, and a real UI surface.
2. Use Tamil DS primitives and tokens before custom styling.
3. Use full-width sections for page structure. Use cards only for repeated entities or contained tasks. Never nest cards.
4. Keep typography calm and authoritative. Tamil text needs generous line-height (use scaled values, never tight overrides) and enough width to wrap naturally.
5. Use one purposeful accent color. Avoid unrelated gradients, decorative blobs, random tinted shadows, or off-brand palettes.
6. Show real content: service names, document rows, form fields, dashboard metrics, messages, statuses, dates, contact paths or civic workflows.
7. Make controls feel like a product: clear labels, focus states, hover states, touch targets, disabled/loading/empty states where relevant.
8. Check mobile and short-height desktop layouts. No clipped Tamil labels, diacritics, pills, floating widgets, popovers or hero text.
9. Final answer must mention files changed, visual behavior changed, and verification results.Visual Quality Specification
Page background should be quiet: white, subtle token-muted bands or brand-specific pale surfaces.
Hero type must be large enough to lead, but not so large that the first viewport loses the workflow.
Use max-w-7xl page containers with px-5 sm:px-8 for major pages unless existing layout differs.
Use py-16 to py-24 for normal sections; compact product heroes may use viewport-aware min-height.
Cards use rounded-md, border, bg-card or white, token shadows and 20-28px padding.
Do not place a card inside another card. Use rows, panels or bordered groups inside cards.
Pill badges must sit inside card padding or have enough grid top padding so they never clip.
Use one primary filled CTA per section. Secondary actions use outline, ghost or text link.
Use lucide icons as semantic markers. Icons should align with title baselines, not float randomly.
Floating widgets use fixed bottom/right, viewport-safe height, scrollable body and anchored composer.
No generic gradients, decorative blobs, oversized marketing hero art or placeholder SVG illustrations.
For brand pages, derive palette from the brand. Do not keep prior page colors after a brand direction changes.
Tamil Content Specification
Default visible UI should be Tamil when the product is for Tamil DS or Tamil public service.
Use English only for proper nouns, official acronyms, file names, package names and commands.
Tamil body copy should use leading-7 or equivalent. Tamil DS auto-scales line-heights only for text content nodes (p, li, span, td) under :lang(ta) / .font-tamil — NOT for the container wrapper.
CRITICAL SCOPING RULE: Never put lang=ta or className=font-tamil on a wrapper element that contains form controls (input, button, checkbox, switch, select, label). The Tamil line-height (1.8) must not bleed into interactive controls — it distorts their height and visual alignment. Apply font-tamil only on individual text nodes.
Do NOT use tight classes like leading-none, leading-tight, leading-snug, or arbitrary small leading-[1.1] / pixel leadings on Tamil text.
Avoid fixed-height containers combined with overflow-hidden on nodes containing Tamil text, as diacritics/vowel markers (e.g. ி, ீ, ு, ூ, ்) will be clipped. Use min-h-* or h-fit with comfortable vertical padding instead.
Avoid narrow chips for long Tamil labels. Let chips wrap or reduce the number shown.
Prefer natural Tamil phrases over transliterated English.
Do not mix Tamil and English in the same navigation label unless the user asks for bilingual UI.
For translation support, provide a clear translate action/control rather than sprinkling English helper labels everywhere.
Government Tamil tone should be calm, official and useful. Avoid salesy phrases.
When building AI chat interfaces, use Skills Tags (clickable slash-command lozenges like /சுருக்கம், /தகுதி, /ஆவணங்கள்) above the input field. Clicking a tag should populate the input with the corresponding command and focus the input.
The Inline Prompt composer should follow the Tamil DS pattern: Plus and Settings2 icons on the left, input field in the center with Tamil placeholder text, Mic icon and submit button on the right.
AI chat responses should be bilingual when using slash commands (e.g. title shows both Tamil and English: சுருக்கம் / Summary) with structured bullet-point answers.
Accessibility Specification
All icon-only controls require aria-label in the visible UI language.
Every interactive element needs focus-visible styling.
Full-page experiences should provide a skip-to-main link.
Do not rely on color alone for status. Use text, icon or label too.
Text must meet contrast expectations against the current background.
Controls should have comfortable touch targets, especially public-service pages.
Overlay and chat panels must be keyboard reachable and closable.
Avoid clipped content at 375px width and short browser heights.
Use semantic headings in order. Do not skip from h1 to random visual-only sections.
When adding accessibility controls, include text size and contrast if the context is public service.
Verification Matrix
Single docs page
eslint changed page, tsc
Run build if nav or metadata changed.
UI primitive
eslint primitive + affected docs, tsc, build
Scan for hardcoded colors/shadows and all variant examples.
Block/page
eslint affected files, tsc, build
Check desktop/mobile layout and first viewport composition.
Navigation update
eslint nav + page, tsc, build
Confirm route appears in build output.
Accessibility fix
eslint, tsc
Also manually reason through keyboard/focus and short viewport behavior.
Tamil content update
eslint changed files, tsc
Scan visible English and check Tamil line wrapping.
Copy-Paste Prompts
Use these prompts exactly when starting work in another AI tool. They are intentionally strict.
Universal Tamil DS agent prompt
You are working on a Tamil DS style project. You may or may not have direct access to the original repository.
Your job is to produce production-quality UI and code that matches Tamil DS design quality.
Required workflow:
1. Treat these instructions as the full source of truth even if you do not have AGENTS.md or repository access.
2. If code access exists, inspect the existing files and patterns before editing. If no code access exists, produce implementation-ready code and explain where it should go.
3. Use design-system primitives for Button, Card, Badge, Input, Table, Dialog, Sheet, Popover, Tooltip, Calendar, Tabs, Pagination and layout helpers.
4. Use existing tokens, theme colors, radius, shadows and spacing. Do not hardcode off-brand blue/purple colors or tinted shadows.
5. Build real workflow content, not placeholder marketing copy.
6. For Tamil/public-service pages, make visible UI Tamil-first and provide translation support separately when needed.
7. Follow the output design contract: compact first viewport, clear hierarchy, deliberate spacing, real UI surface, aligned cards, token-based controls and no clipped content.
8. Add accessibility: focus states, aria-labels, keyboard paths, skip-to-main, contrast and responsive text behavior.
9. Check mobile, tablet, desktop and short browser heights.
10. If code access exists, verify with targeted eslint, npx tsc --noEmit and npm run build for broad changes.
11. If code access does not exist, provide a QA checklist and clear file-by-file implementation plan.
Design quality bar:
- First viewport is complete, useful and visually polished.
- One primary action per section.
- No nested cards.
- No clipped Tamil text, overlapping lines, or clipped diacritics. Avoid tight leading classes (leading-none/tight/snug) and fixed heights with overflow-hidden on Tamil text. Ensure lang='ta' or .font-tamil is present.
- No off-brand hardcoded colors or tinted shadows.
- Visual anchor is real: dashboard, service surface, form, table, document, calendar, chat or civic interface.
- Final answer states changed files and verification commands when available.No repository access prompt
You only have this instruction URL and no repository access.
Still produce a complete implementation plan:
1. Restate the target page or component.
2. Define the information architecture and first viewport.
3. List the components/primitives that should be used.
4. Provide implementation-ready JSX/TSX sections.
5. Provide token-friendly styling guidance without hardcoded off-brand colors.
6. Include Tamil-first copy when the context is Tamil/public service.
7. Include accessibility behavior and responsive QA checks.
8. Include exact output design instructions: first viewport, hierarchy, spacing, cards, controls, Tamil text behavior and responsive behavior.
9. End with a file placement plan and verification checklist for the developer who will apply it.Component documentation prompt
When editing or creating a component page:
1. If code access exists, read the primitive implementation first.
2. If code access exists, read one nearby docs page for structure.
3. Show real variants, states and sizes.
4. Anatomy must match the actual rendered component.
5. Do/don't examples must be different and must demonstrate the rule.
6. Preview backgrounds must be subtle and must not dominate the component.
7. Ensure Tamil labels fit in every example.
8. Run eslint for the page and primitive, then tsc.Block or page prompt
When creating or editing a block:
1. Define the audience and primary workflow.
2. Make the first viewport useful: header, hero, action/search, trust signal and visual mockup.
3. Use sections, not cards, for page structure.
4. Use cards only for repeated services, schemes, documents, updates or people.
5. Keep brand palette consistent across buttons, badges, icons, shadows and mockups.
6. Add support states: help, contact, empty/loading/status when relevant.
7. Check mobile and short viewport behavior.
8. Run eslint, tsc and build.Kural AI chat interface prompt
When building AI chat interfaces in Tamil DS:
1. Use the Inline Prompt composer pattern: Plus and Settings2 icons on the left, input field in the center, Mic icon and submit ArrowUp button on the right.
2. Add Skills Tags above the input field as clickable lozenges. Each tag uses: rounded-md border border-border bg-muted/50 px-2.5 py-0.5 text-xs font-semibold with a / prefix in muted color.
3. Clicking a skill tag should set the input value to the corresponding slash command (e.g. /சுருக்கம் ) and focus the input field using a React ref.
4. Implement slash command parsing in getAIReply: match commands like /சுருக்கம், /தகுதி, /ஆவணங்கள், /விண்ணப்பம், /தொடர்பு and their English equivalents.
5. AI responses should return structured objects with bilingual titles (Tamil / English), descriptive text, and bullet-point checklists.
6. Add a helper footer below the input: "AI பயன்படுத்தப்படுகிறது. முடிவுகளை சரிபார்க்கவும்." with an Info icon.
7. For floating chat (FloatingKuralChat), use rounded-[22px] input wrapper with focus-within:border-emerald-600 ring.
8. For static chat (KuralAIChatSection), use rounded-md input wrapper with focus-within ring.
9. Both chat variants must include the skill tags, inline prompt icons, and the bilingual slash command response system.
10. Import Plus, Settings2, Mic, Wand2, ListPlus from lucide-react. Use useRef for input focus management.Failure Modes and Fixes
Generic output
The page looks polished but says nothing specific.
Replace filler with real domain content, official labels, workflows and data.
Wrong theme
The page keeps colors from the previous design.
Extract brand colors and replace accents, shadows, badges and mockups consistently.
Card misuse
Cards are nested or used as page sections.
Use full-width sections and reserve cards for repeated items.
Tamil clipping
Tamil labels/diacritics collide vertically or get clipped by container borders.
Use auto-scaled line-heights, avoid leading-none/tight/snug and fixed-heights with overflow-hidden, use py-* and h-fit.
font-tamil on wrapper
Checkbox, Switch, Input or Button inside a lang=ta or .font-tamil wrapper renders with wrong height because line-height: 1.8 bleeds in from the container.
NEVER put lang=ta or .font-tamil on a div/Card/CardContent that wraps interactive controls. Apply font-tamil only on individual Label, p, or span text nodes.
Radix UI usage
Importing from @radix-ui/* in new or modified primitives.
This project uses @base-ui/react — NOT Radix UI. All primitive imports must be from @base-ui/react/<component>. State attrs: data-checked, data-unchecked, data-open, data-disabled.
Tailwind config
Creating tailwind.config.js or using @apply with config-based tokens.
Tailwind v4 is CSS-first. All tokens live in @theme {} blocks in globals.css. There is no tailwind.config.js. Use CSS custom properties directly.
Preview mismatch
Do and don't examples show the same UI.
Create distinct examples matching the rule and the component variant.
Half-built workflow
Hero looks good but service flow, empty states or support routes are missing.
Build the actual usable experience and supporting states.
Unverified code
Imports, route build or types fail after a visual change.
Run targeted eslint, tsc and build before final response.
Missing AI patterns
Chat interface uses a plain input without skill tags or inline prompt icons.
Add Skills Tags above the input, use the Tamil DS inline prompt layout (Plus, Settings2, Mic icons), and implement slash command parsing in the AI reply logic.
Diacritic collision
Tamil vowel marks overlap between lines or get cut by container edges.
Set lang=ta on root element, use .font-tamil class on text nodes only. Never combine fixed heights with overflow-hidden on Tamil text containers.
Non-negotiables
- No placeholder content in final UI.
- No hardcoded off-brand colors in reusable components.
- No nested cards.
- No clipped Tamil labels or pills.
- No final response without saying what was verified.
Definition of done
The work is done only when the output feels native to Tamil DS, uses the correct primitives, follows the active brand and Tamil content rules, includes accessibility behavior, and passes the relevant checks. Anything less is a draft.
Final response format for AI tools
Mention changed files, summarize behavior and design changes, list verification commands, and call out anything not completed. Do not over-explain implementation details unless the user asks.
Full Tamil Site Building Guide
Need to build a complete Tamil-first website from scratch? The Tamil Site Building Guide covers end-to-end setup: HTML root configuration, font loading, typography safety, component usage, Kural AI integration, accessibility, and deployment.
Read the Tamil Site Building Guide