---
title: Introduction
description: A shadcn-style mobile component library for Angular, React, and Vue — Material 3 on Android, liquid glass on iOS. Own your code.
sidebar:
  label: Introduction
  icon: rocket
---

**touchcn** is a component library for mobile web and cross-platform apps. Components adapt to the
platform at runtime: **Material Design 3 on Android**, an **iOS liquid-glass** frosted look on iOS —
one component set, no per-platform branching in your code.

## Not a component package

touchcn follows the distribution model popularized by [shadcn/ui](https://ui.shadcn.com) — if you're
used to installing a component library from npm (Ionic, Angular Material, MUI), this works differently:

- **Components are source you own.** `npx touchcn add button` copies the styled component source into
  your project. You import it from your own codebase and can edit every line — there is no opaque
  package to fight or fork.
- **Only the engine is an npm dependency.** Platform detection, theming, and behavior primitives ship
  as small versioned packages; the components you copy are thin, styled compositions on top of them.
- **Updates still reach you.** The CLI records what it installed: `npx touchcn diff` shows what
  changed upstream, and `npx touchcn update` applies it — three-way merging into files you've edited
  instead of overwriting them. See [Updating components](/docs/components#updating-components).

:::tip
**The easiest way to get started is an AI agent.** touchcn ships [agent skills](/docs/skills) for
Claude Code, Cursor, and other compatible tools — install them once and your agent handles the
setup, wiring, and conventions for you:

```bash
npx skills add capawesome-team/touchcn --skill touchcn
npx skills add capawesome-team/touchcn --skill touchcn-ionic-migration
```

Then just ask: *"add touchcn to this project"* or *"migrate this Ionic app to touchcn"*.
:::

:::note
**Coming from Ionic?** touchcn can run alongside Ionic and be adopted screen by screen — see the
[Ionic guide](/docs/guides/ionic) for coexistence rules and a migration path, and the
[component name mapping](/docs/components#component-naming) for where `ion-*` components land here.
The dedicated `touchcn-ionic-migration` [agent skill](/docs/skills) automates exactly this migration.
:::

## Why touchcn

<CardGroup cols={2}>
  <Card title="Own your code" icon="git-fork">
    The CLI copies styled sources into your project. Edit them freely — nothing is imported from an
    opaque package.
  </Card>
  <Card title="Platform-adaptive" icon="smartphone">
    Material 3 on Android, iOS 26 liquid glass on iOS. The same components re-skin themselves at
    runtime.
  </Card>
  <Card title="Angular, React & Vue" icon="layers">
    Identical component set, one registry per framework. Same `tcn-*` classes and behavior across all three.
  </Card>
  <Card title="Updates without lock-in" icon="refresh-cw">
    The CLI pulls upstream fixes into your copied components — three-way merging files you've edited.
  </Card>
</CardGroup>

## How it fits together

Four layers stack together — you depend on the first three and copy the fourth into your app:

1. **Core** (`@touchcn/core`) — framework-agnostic platform detection, `AppearanceManager`, `cn()`.
2. **Tailwind** (`@touchcn/tailwind`) — a Tailwind v4 CSS-first token preset with `.ios` / `.md` namespaces.
3. **Headless** (`@touchcn/angular` / `@touchcn/react` / `@touchcn/vue`) — unstyled behavior and accessibility primitives.
4. **Registry** (`touchcn add …`) — styled components wiring layers 1–3 together, copied in via the CLI.

## Where to next

<CardGroup cols={2}>
  <Card title="Getting started" icon="download" href="/docs/getting-started">
    Install the engine, wire up Tailwind and the provider, and add your first component.
  </Card>
  <Card title="Theming" icon="palette" href="/docs/theming">
    Token namespaces, color scheme, and Material You dynamic color.
  </Card>
  <Card title="Components" icon="layout-grid" href="/docs/components/button">
    Browse the full component set with live, platform-switchable previews.
  </Card>
  <Card title="GitHub" icon="github" href="https://github.com/capawesome-team/touchcn">
    Source, issues, and the registry that powers the CLI.
  </Card>
</CardGroup>