> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Design systems

> The starting design system every vly project ships with — Tailwind tokens, shadcn/ui components, theme primitives — and how to extend it.

Every vly project ships with a working design system based on **Tailwind CSS** + **shadcn/ui**. It's not a heavy abstraction — most files are plain Tailwind classes and standard shadcn components. Edit anything you don't like.

## What's included

<CardGroup cols={2}>
  <Card title="Tailwind v4" icon="paintbrush" href="/features/design/tailwind-config">
    Modern Tailwind with CSS-variable-based theming.
  </Card>

  <Card title="shadcn/ui" icon="boxes" href="/features/design/shadcn-components">
    50+ accessible components, **owned by your project** (not imported from a library).
  </Card>

  <Card title="Light + dark themes" icon="sun-moon" href="/features/design/themes">
    Auto-switching, system-preference-aware.
  </Card>

  <Card title="Typography scale" icon="type" href="/features/design/typography">
    Inter by default; swap fonts with one prompt.
  </Card>

  <Card title="Lucide icons" icon="image" href="/features/design/icons-and-assets">
    Modern icon library; 1,000+ icons.
  </Card>

  <Card title="Responsive previews" icon="smartphone" href="/features/design/responsive-previews">
    Mobile / tablet / desktop side-by-side.
  </Card>
</CardGroup>

## How it's structured

Three layers:

```
tailwind.config.ts          # tokens (colors, spacing, fonts)
       ↓
components/ui/*.tsx         # shadcn primitives (Button, Card, Dialog, etc.)
       ↓
components/{feature}/*.tsx  # composed app components
```

The bottom layer (your composed components) consumes the middle layer (shadcn primitives) which uses the top layer (Tailwind tokens). Change a token and everything that consumes it updates.

## Extending

<Steps>
  <Step title="Customize tokens">
    Edit `tailwind.config.ts` to change brand color, spacing scale, or fonts.
  </Step>

  <Step title="Customize primitives">
    Edit `components/ui/button.tsx` (etc.) to change shadcn defaults. Your changes are permanent for the project.
  </Step>

  <Step title="Compose new components">
    Build domain-specific components in `components/{feature}/`. They use the primitives.
  </Step>
</Steps>

## Tips

<Tip>
  **Start with tokens.** A brand color change at the token level cascades to every button, link, and active state without touching individual files.
</Tip>

<Tip>
  **Don't fight shadcn.** It's a sensible default; the components are accessible and well-tested. Customize *within* the variants pattern rather than replacing components wholesale.
</Tip>

## Related

<CardGroup cols={3}>
  <Card title="Themes" icon="palette" href="/features/design/themes">
    Light / dark / brand colors.
  </Card>

  <Card title="Tailwind config" icon="settings-2" href="/features/design/tailwind-config">
    The token file.
  </Card>

  <Card title="shadcn/ui components" icon="boxes" href="/features/design/shadcn-components">
    The primitive library.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.