# Kontenedor — rules for AI agents
- Use semantic Tailwind tokens (bg-background, text-foreground, bg-surface, bg-muted, text-muted-foreground, border-border, bg-primary, text-primary-foreground, bg-success-subtle…). Never hard-code hex colors.
- Use border-k (not border) so borders follow the weight; use focus-ring on custom interactive elements.
- Font weights: font-body, font-medium, font-strong, font-heading; headings add tracking-heading.
- Radius: rounded-xs|sm|md|lg|xl|2xl. Shadows: shadow-xs|sm|md|lg. All change per weight.
- Weight: data-weight="thin|medium|bold" on or any subtree. Variants thin: and bold:. Dark mode: class "dark".
- Icons: ; Buttons take leadingIcon / trailingIcon names.
- Mobile-first; container-k for page gutters; text-display-md|lg|xl for hero headings.
- Prefer existing components: utils, tokens, accordion, alert-dialog, alert, aspect-ratio, avatar, badge, breadcrumb, button-group, button, calendar, card, carousel, chart, checkbox, collapsible, combobox, command, commerce, context-menu, date-picker, dialog, dropdown-menu, empty-state, field, hover-card, icon, input-otp, input, item, kbd, label, layout, logo, menubar, navigation-menu, pagination, popover, progress, radio-group, resizable, scroll-area, select, separator, skeleton, slider, spinner, stat, steps, switch, table, tabs, toast, toggle, tooltip, typography, block-checkout, block-data-table, block-settings-form, block-sign-in, section-app-shell, section-content, section-hero, section-marketing, section-navbar, template-blog, template-corporate, template-dashboard, template-ecommerce.
---
# Introduction
**Kontenedor** is a professional design system for designers, developers and AI agents. It gives you one source of truth — design tokens — expressed as **CSS variables**, a **Tailwind CSS v4 theme**, **React components** you own, a **Figma library** with Variables, and a **machine-readable registry** for AI.
## Principles
1. **Tokens first.** Components never hard-code colors, radii or shadows; they use semantic tokens such as `bg-primary` or `rounded-md`.
2. **Own the code.** Components are copied into your project with the CLI. Change anything — no black box.
3. **Accessible by default.** Built on Radix primitives: keyboard, focus and ARIA handled. WCAG AA contrast in light and dark.
4. **Three weights.** The same component renders as **Thin**, **Medium** or **Bold** by switching one attribute.
5. **Responsive.** Mobile-first, fluid type, touch-friendly sizes.
6. **AI-ready.** An MCP server, `llms.txt` and `AGENTS.md` teach AI tools to build with Kontenedor.
## What's inside
| Layer | Package | Free preview | Pro ($49 lifetime) |
| --- | --- | --- | --- |
| Tokens | `@kontenedor/tokens` | ✓ | ✓ |
| Core components | Button, Badge, Card, Input, Field, Icon… | ✓ | ✓ |
| Full library | Forms, overlays, navigation, data, charts, commerce | — | ✓ |
| Figma library | Variables + components | Preview | ✓ |
| Patterns | Dashboard, CRM, e-commerce, email | Storybook | ✓ (source) |
| CLI & MCP | `kontenedor`, `@kontenedor/mcp` | Free items | All items |
## Built for
Websites, landing pages, dashboards, internal systems, CRM, ERP, e-commerce, email campaigns and presentations — see [Project types](/docs/project-types).
Continue with [Installation](/docs/installation).
---
# Installation
Kontenedor works with any React framework (Next.js, Vite, Remix, Astro) and **Tailwind CSS v4**.
## 1. Initialize
```bash
npx kontenedor init
```
This creates `kontenedor.json`, copies the tokens (`styles/kontenedor.css`, `styles/tailwind.css`) and the `cn()` utility, and installs `clsx` and `tailwind-merge`.
## 2. Import the styles
In your main CSS file:
```css
@import "tailwindcss";
@import "./components/kontenedor/styles/tailwind.css";
@source "./components/kontenedor";
```
## 3. Load Google Fonts and Material Symbols
```html
```
In Next.js put these in `app/layout.tsx` inside `
`.
## 4. Add components
```bash
npx kontenedor add button card input
npx kontenedor add --all # everything your license allows
```
Dependencies (other components, npm packages) are resolved automatically.
## 5. Pro license
After purchase, Polar emails your license key. Add it once:
```bash
npx kontenedor login kt_your_license_key
# or set the environment variable
export KONTENEDOR_LICENSE=kt_your_license_key
```
## 6. Use it
```tsx
import { Button } from "@/components/kontenedor/ui/button";
export default function Page() {
return ;
}
```
Set the weight on `` (or `thin` / `bold`) and the theme with the `dark` class.
## Alternative: clone the repository
Buyers get access to the private GitHub repository. You can use the monorepo directly (`pnpm install && pnpm storybook`) or consume `packages/ui` as a workspace package.
---
# Components
Explore every component, variant and state live in **[Storybook](/storybook)** — switch weight and theme from the toolbar.
| Category | Components |
| --- | --- |
| Foundation | Icon, Logo, Typography (H1–H4, Lead, Prose…), Layout, Aspect Ratio, Scroll Area, Resizable |
| Actions | Button, Button Group, Toggle, Toggle Group, Badge, Kbd |
| Forms | Input, Textarea, Label, Field, Checkbox, Radio Group, Switch, Select, Combobox, Slider, Input OTP, Calendar, Date Picker, Date Range Picker |
| Navigation | Navbar, Navigation Menu, Sidebar, App Shell, Menubar, Tabs, Accordion, Collapsible, Breadcrumb, Pagination, Steps, Dropdown Menu, Context Menu, Command |
| Overlays | Dialog, Alert Dialog, Sheet / Drawer, Popover, Hover Card, Tooltip, Toast |
| Data display | Card, Item, Table, Avatar, Stat, Charts, Progress, Skeleton, Empty State, Alert, Carousel |
| Commerce | Price, Rating, ProductCard |
| Sections | Hero (centered, split, image), Page header, Logo cloud, Feature grid, Feature split, Stats, Testimonials, Pricing, CTA, FAQ, Newsletter, Team, Post card/grid, Article header, Contact, Footer |
| Blocks | Data table, Sign-in, Settings form, Checkout |
| Templates | Dashboard / CRM, E-commerce, Blog / Magazine, Corporate / B2B — see [/templates](/templates) |
## Conventions
- Every component accepts `className` and merges it with `cn()`.
- Variants are defined with `cva` and exported (`buttonVariants`) so you can reuse styles.
- `asChild` renders the styles on your own element (e.g. a Next.js `Link`).
- Icons are passed by **Material Symbols name**: `leadingIcon="add"`.
- Parts expose `data-slot` attributes for targeted styling.
## Example
```tsx
```
## Icons
Kontenedor uses **Google Material Symbols (Rounded)** — 3,000+ icons. Browse them at [fonts.google.com/icons](https://fonts.google.com/icons) and use the name:
```tsx
```
---
# Weights
A **weight** is a coordinated set of tokens that changes the visual intensity of every component at once. Components stay identical in API and structure.
| Token | Thin | Medium | Bold |
| --- | --- | --- | --- |
| Border width | 1px | 1px | 2px (ink) |
| Radius md | 4px | 8px | 12px |
| Shadows | none | soft | hard offset |
| Body / heading weight | 300 / 300 | 400 / 600 | 500 / 800 |
| Icon stroke (Material Symbols `wght`) | 200 | 400 | 600, filled |
| Control height md | 36px | 40px | 44px |
| Focus ring | 1px | 2px | 3px |
## Switching
```html
```
```tsx
import { KontenedorScope } from "@/components/kontenedor/ui/layout";
…
```
## Weight-aware utilities
Use these in your own components so they respond to the weight:
- `border-k`, `border-k-t`, `border-k-b` — border width follows the weight.
- `focus-ring` — accessible focus outline.
- `press` — tactile press offset (Bold only).
- `font-body`, `font-medium`, `font-strong`, `font-heading` and `tracking-heading`.
- Variants `thin:` and `bold:` — e.g. `bold:shadow-md thin:border-border`.
## When to use each
- **Thin** — editorial, luxury, portfolios, marketing sites, email.
- **Medium** — SaaS, dashboards, CRM, ERP, e-commerce. The default.
- **Bold** — campaigns, launches, keynotes, gaming, education, expressive brands.
You can mix them: a Medium product with a Bold marketing hero.
---
# Design tokens
Tokens are defined once in `packages/tokens/src/tokens.mjs` and generated into:
- `kontenedor.css` — framework-agnostic CSS variables (`--k-*`).
- `tailwind.css` — the Tailwind v4 `@theme`, utilities and variants.
- `tokens.json` — W3C Design Tokens (DTCG) format.
- `figma-variables.json` — collections and modes for Figma.
## Layers
1. **Primitives**: raw palettes (`ink`, `cobalt`, `green`, `amber`, `red`, `cyan`) in OKLCH.
2. **Semantic roles**: what components use (`background`, `foreground`, `surface`, `muted`, `border`, `primary`, `success`…).
3. **Weight**: radius, borders, shadows, font weights, icon axes, control heights.
## Color roles
| Role | Tailwind | Use |
| --- | --- | --- |
| background / foreground | `bg-background text-foreground` | Page |
| surface | `bg-surface` | Cards, panels |
| muted / muted-foreground | `bg-muted text-muted-foreground` | Secondary text, fills |
| subtle | `bg-subtle` | Hover rows, sections |
| border / border-strong / input | `border-border` | Dividers, outlines |
| primary (+ -foreground, -subtle) | `bg-primary` | Main actions, brand |
| success · warning · danger · info | `bg-success-subtle` | Status |
| inverse | `bg-inverse` | Tooltips, high contrast |
| chart-1…5 | `var(--k-chart-1)` | Data viz |
Every color has a dark-mode value. Raw palettes are available as `bg-k-cobalt-500`, but prefer semantic roles.
## Typography
- **Geist** (sans) and **Geist Mono** from Google Fonts.
- Scale `text-2xs` → `text-7xl`, plus fluid `text-display-md|lg|xl` for hero headings.
## Breakpoints
| Name | Min width | Device |
| --- | --- | --- |
| `sm` | 640px | Large phones |
| `md` | 768px | Tablet |
| `lg` | 1024px | Desktop |
| `xl` | 1280px | Wide desktop |
| `2xl` | 1536px | Ultra-wide |
## Motion
`--k-duration-fast` 120ms · `--k-duration-base` 180ms · `--k-duration-slow` 280ms · `--k-ease-out`. `prefers-reduced-motion` is respected globally.
---
# Theming & branding
## Dark mode
Add the `dark` class (or `data-theme="dark"`) to `` or any element. All semantic tokens switch.
## Your brand color
Override the semantic variables after importing Kontenedor:
```css
:root {
--k-primary: oklch(0.62 0.19 150); /* green brand */
--k-primary-foreground: oklch(1 0 0);
--k-primary-subtle: oklch(0.96 0.04 150);
--k-primary-subtle-foreground: oklch(0.45 0.13 150);
--k-ring: oklch(0.62 0.19 150);
}
.dark { --k-primary: oklch(0.7 0.18 150); }
```
## Your fonts
```css
:root { --k-font-sans: "Inter", sans-serif; --k-font-display: "Space Grotesk", sans-serif; }
```
Any Google Font works. Variable fonts get the most out of the weights.
## Multiple brands
Scope variables to a class (`.brand-acme { --k-primary: … }`) to run several brands — for agencies, white-label products or multi-tenant SaaS — on the same components.
---
# Responsive design
Kontenedor is **mobile-first**: base styles target phones and grow with `md:` (tablet) and `lg:` (desktop).
## Rules
- **Gutters**: 16px mobile → 32px tablet → 40px desktop (`container-k` or ``).
- **Touch targets**: controls are ≥ 36px (Thin) / 40px (Medium) / 44px (Bold).
- **Type**: hero headings use fluid `text-display-*` that scale with the viewport.
- **Tables** scroll horizontally on small screens; hide low-priority columns with `hidden md:table-cell`.
- **Navigation**: collapse to a `Sheet` below `lg`.
- **Dialogs** become full-width with margins on mobile; use `SheetContent side="bottom"` for mobile actions.
- **Grids**: `grid sm:grid-cols-2 lg:grid-cols-4` for stat rows and product grids.
## Test sizes
Storybook includes Mobile (375), Tablet (768) and Desktop (1440) viewports. Figma frames use the same sizes.
---
# Figma library
The Figma library mirrors the code 1:1 — same token names, same component names, same variants.
## Variables
| Collection | Modes | Contains |
| --- | --- | --- |
| Primitives | Value | ink, cobalt, green, amber, red, cyan, lime, violet |
| Color | Light, Dark | All semantic roles (background, primary, border…) |
| Weight | Thin, Medium, Bold | radius, border width, font weights, icon weight, control heights |
Switch a frame's **Color** mode to Dark and **Weight** mode to Bold and every component updates — exactly like `data-weight` in code.
## Components
Built with auto-layout and component properties (variant, size, state, icon, label). Names match React props: `Button / variant=primary, size=md`.
## Fonts & icons
Install **Geist**, **Geist Mono** and **Material Symbols Rounded** from Google Fonts. Icons are typed as ligatures (e.g. `home`) so they match code.
## Access
Buyers receive the library link by email (Polar benefit). Duplicate it into your team, then **Publish** it as a team library.
## Designer → developer handoff
Component names, variants and token names are identical in Figma and code. With **Figma Dev Mode** + **Code Connect**, inspecting a component shows the Kontenedor React snippet.
## Free preview
A preview of the Figma library (cover, foundations, core components and the four templates) is available on the Figma Community — see the **Figma preview** button on the [home page](/#pricing). The full library with every component is delivered to buyers.
---
# AI & MCP
Kontenedor is designed so AI coding agents produce on-brand, consistent UI.
## MCP server
Add the server to Claude Code, Cursor, VS Code, Windsurf or any MCP client:
```json
{
"mcpServers": {
"kontenedor": {
"command": "npx",
"args": ["-y", "@kontenedor/mcp"],
"env": { "KONTENEDOR_LICENSE": "kt_your_license_key" }
}
}
}
```
Claude Code one-liner:
```bash
claude mcp add kontenedor -e KONTENEDOR_LICENSE=kt_… -- npx -y @kontenedor/mcp
```
### Tools
| Tool | What it does |
| --- | --- |
| `list_components` | Catalog with category, description and access level |
| `get_component` | Full source + dependencies for a component |
| `get_tokens` | Tokens as CSS, Tailwind or JSON |
| `get_guidelines` | Usage rules: weights, layout, a11y, project types |
| `search_icons` | Suggests Material Symbols names for a concept |
## llms.txt
- [`/llms.txt`](/llms.txt) — concise index for LLMs.
- [`/llms-full.txt`](/llms-full.txt) — complete docs + component API in one file.
Paste the URL into ChatGPT, Claude, v0, Lovable or Bolt: *"Use the Kontenedor design system from https://kontenedor.com/llms-full.txt"*.
## AGENTS.md
Copy `AGENTS.md` from the repository into your project root. It tells agents to:
- use semantic tokens (`bg-primary`) — never raw hex;
- use Kontenedor components before writing new ones;
- use `Icon` with Material Symbols names;
- respect `data-weight` and dark mode;
- design mobile-first.
## Prompts that work well
- "Build a CRM customers page with Kontenedor: Stat row, filters, Table with Badge statuses, Pagination. Medium weight."
- "Create a Bold-weight launch landing page with a hero, 3 feature cards and pricing."
- "Make a Thin-weight checkout with Steps, Field inputs and a summary Card."
---
# Project types
Kontenedor ships recipes for the products teams build most.
## Marketing websites & landing pages
`Section`, `SectionHeader`, `Container`, Button `size="lg"`, `Card`, `Accordion` (FAQ). Consider **Thin** for editorial or **Bold** for campaigns. Use `text-display-*` for heroes.
## Dashboards & analytics
App shell (sidebar + topbar), `Stat` row, `BarChart` / `DonutChart` / `Sparkline`, `Tabs` for ranges, `Table`. **Medium** weight. See *Patterns → Dashboard* in Storybook.
## Systems, CRM & ERP
Dense `Table` with `Badge` statuses, `DropdownMenu` row actions, `Dialog` / `Sheet` forms with `Field`, `Pagination`, `Breadcrumb`, `EmptyState`, `Toast` feedback. **Medium** weight. Reduce paddings for density.
## E-commerce
`ProductCard`, `Price`, `Rating`, `Steps` for checkout, `Select` for variants, `Sheet` for cart and filters. Any weight — Bold works great for streetwear and youth brands; Thin for luxury.
## Email campaigns
Email clients don't support CSS variables or modern CSS. Use the token values from `tokens.json` (hex in `figma-variables.json`) with React Email or MJML: 600px max width, Geist with Arial fallback, table layouts, bulletproof buttons using `primary`. **Thin** and **Medium** read best in inboxes.
## Presentations & slides
Pitch decks, reports, workshops and keynotes. Design slides at **1920×1080 (16:9)** in Figma or build them in code as `aspect-video` frames. Use `text-display-*` for titles, `Stat` and charts for data slides, and `Card` grids for comparisons. Keep one idea per slide. **Bold** for keynotes and launches, **Thin** for editorial reports, **Medium** for business reviews. See *Patterns → Presentation* in Storybook.
---
# License
**Free preview** — the tokens and the free components may be used in any personal or commercial project.
**Kontenedor Pro (lifetime, $49)** — one person (or one seat) may use the full library, Figma files, patterns, CLI and MCP in **unlimited personal and commercial projects**, including client work, and receive all future updates.
You may **not**:
- resell, redistribute or sublicense Kontenedor (code or Figma) as a design system, UI kit, template or theme;
- share your license key or repository access;
- create a competing product with Kontenedor's source.
Purchases are processed by Polar (merchant of record). Questions: reply to your Polar receipt email.