Getting Started

What is Viana Kit?

An AI-native design system built on React, Tailwind CSS v4, and shadcn/ui — architected for both human developers and AI agents.

Three Ways to Use Viana Kit

For Developers

Clone the starter kit and build your app with pre-configured components. No setup required.

For ProductSoon

Build rapid prototypes with Skills and MCP. Connect AI agents to generate compliant code.

For DesignersSoon

Link to Figma, Paper.design, and Pencil.dev. Generate mockups rapidly from design systems.

For Developers

The fastest way to start is to clone the viana-kit starter — a blank canvas pre-wired with all components, Tailwind v4, and the correct directory structure.

bash

# Clone the starter kit
git clone https://github.com/kevinmeldcx/viana-kit.git my-app
cd my-app

# Install dependencies
npm install

# Start the dev server
npm run dev

Visit the repository for the latest components and documentation:

bash

https://github.com/kevinmeldcx/viana-kit

The Governance Rule

Important

Never modify files inside src/components/ui/. That directory is treated as read-only and will be overwritten when brand updates are pushed.

If a component needs project-specific behavior or extended styling, create a wrapper outside the ui/ directory that imports and extends the Viana Kit primitive.

src/components/submit-button.tsx

// Correct — wrap the primitive, extend in your own file
import { AppButton, type AppButtonProps } from "@/components/primitives/AppButton"

interface SubmitButtonProps extends AppButtonProps {
  loading?: boolean
}

export function SubmitButton({ loading, children, ...props }: SubmitButtonProps) {
  return (
    <AppButton disabled={loading} {...props}>
      {loading ? "Saving…" : children}
    </AppButton>
  )
}

Component Layers

Viana Kit components are organized into three tiers, each with a distinct responsibility.

Directory	Contents	Editable?
components/ui/	Raw shadcn/ui primitives, brand-adjusted	No
components/primitives/	Viana Kit wrappers with enforced defaults	No
components/blocks/	Product-level compositions built from primitives	Yes

For AI Agents

Viana Kit is designed to be AI-agent friendly. Every component page includes machine-readable metadata: canonical IDs, related components, enforcement levels, and platform tags — so AI agents can reason about the design system with the same depth a senior engineer would.

Coming Soon

• MCP server for IDE integration
• Skills for rapid prototyping
• Auto-generated component documentation